@fedify/vocab-runtime 2.4.0-pr.936.41 → 2.5.0-dev.2271

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.4.0-pr.936.41+59c7432c",
+  "version": "2.5.0-dev.2271+49d937e2",
   "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",
@@ -52,6 +52,26 @@
       "require": "./dist/internal/jsonld-cache.cjs",
       "default": "./dist/internal/jsonld-cache.js"
     },
+    "./internal/portable-dereference": {
+      "types": {
+        "import": "./dist/internal/portable-dereference.d.ts",
+        "require": "./dist/internal/portable-dereference.d.cts",
+        "default": "./dist/internal/portable-dereference.d.ts"
+      },
+      "import": "./dist/internal/portable-dereference.js",
+      "require": "./dist/internal/portable-dereference.cjs",
+      "default": "./dist/internal/portable-dereference.js"
+    },
+    "./internal/signed-representation": {
+      "types": {
+        "import": "./dist/internal/signed-representation.d.ts",
+        "require": "./dist/internal/signed-representation.d.cts",
+        "default": "./dist/internal/signed-representation.d.ts"
+      },
+      "import": "./dist/internal/signed-representation.js",
+      "require": "./dist/internal/signed-representation.cjs",
+      "default": "./dist/internal/signed-representation.js"
+    },
     "./temporal": {
       "types": {
         "import": "./dist/temporal.d.ts",
@@ -76,10 +96,11 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "^24.2.1",
+    "@types/node": "^24.12.2",
     "fetch-mock": "^12.5.4",
     "tsdown": "^0.22.0",
-    "typescript": "^6.0.0"
+    "typescript": "^6.0.0",
+    "@fedify/fixture": "2.0.0"
   },
   "dependencies": {
     "@js-temporal/polyfill": "^0.5.1",
@@ -96,6 +117,8 @@
     "build": "pnpm --filter @fedify/vocab-runtime... run build:self",
     "prepublish": "pnpm build",
     "pretest": "pnpm build",
-    "test": "cd dist/tests && node --test"
+    "test": "cd dist/tests && node --test",
+    "pretest:bun": "pnpm build",
+    "test:bun": "node scripts/test-bun.mjs"
   }
 }

package/scripts/test-bun.mjs

@@ -0,0 +1,17 @@
+import { access, glob } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+
+const sources = await Array.fromAsync(glob("src/**/*.test.ts"));
+if (sources.length === 0) throw new Error("No vocab-runtime tests found.");
+
+const tests = sources.map((source) =>
+  source.replaceAll("\\", "/").replace(/^src\//, "dist/tests/")
+    .replace(/\.ts$/, ".mjs")
+).sort();
+for (const test of tests) await access(test);
+
+const result = spawnSync("bun", ["test", "--timeout", "60000", ...tests], {
+  stdio: "inherit",
+});
+if (result.error) throw result.error;
+process.exitCode = result.status ?? 1;

package/src/body.test.ts

@@ -0,0 +1,125 @@
+import { deepStrictEqual, ok, rejects } from "node:assert/strict";
+import { test } from "node:test";
+import { gunzipSync, gzipSync } from "node:zlib";
+import { BodyTooLargeError, readBoundedText } from "./body.ts";
+
+const url = "https://example.com/document";
+
+test("readBoundedText handles empty bodies and flushes incomplete UTF-8", async () => {
+  deepStrictEqual(await readBoundedText(new Response(null), 1, url), "");
+  deepStrictEqual(await readBoundedText(new Response(""), 1, url), "");
+  deepStrictEqual(
+    await readBoundedText(new Response(new Uint8Array([0xe2, 0x82])), 2, url),
+    "\ufffd",
+  );
+});
+
+test("readBoundedText counts bytes and preserves split UTF-8", async () => {
+  const bytes = new TextEncoder().encode('"안녕"');
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const byte of bytes) controller.enqueue(new Uint8Array([byte]));
+      controller.close();
+    },
+  });
+  deepStrictEqual(
+    await readBoundedText(new Response(stream), bytes.length, url),
+    '"안녕"',
+  );
+  await rejects(
+    readBoundedText(new Response(bytes), bytes.length - 1, url),
+    BodyTooLargeError,
+  );
+});
+
+test("readBoundedText rejects a declared oversized body without pulling", async () => {
+  let pulled = false;
+  let canceled = false;
+  const response = new Response(
+    new ReadableStream({
+      pull() {
+        pulled = true;
+      },
+      cancel() {
+        canceled = true;
+      },
+    }, { highWaterMark: 0 }),
+    { headers: { "Content-Length": "100" } },
+  );
+  await rejects(readBoundedText(response, 10, url), BodyTooLargeError);
+  deepStrictEqual(pulled, false);
+  deepStrictEqual(canceled, true);
+  deepStrictEqual(response.body?.locked, false);
+});
+
+test("readBoundedText cancels chunked bodies despite absent or false lengths", async () => {
+  for (const length of [undefined, "1", "invalid"]) {
+    let pulls = 0;
+    let canceled = false;
+    const stream = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        pulls++;
+        controller.enqueue(new Uint8Array(4));
+      },
+      cancel() {
+        canceled = true;
+      },
+    }, { highWaterMark: 0 });
+    const response = new Response(stream, {
+      headers: length == null ? {} : { "Content-Length": length },
+    });
+    await rejects(readBoundedText(response, 8, url), BodyTooLargeError);
+    deepStrictEqual(pulls, 3);
+    deepStrictEqual(canceled, true);
+    deepStrictEqual(response.body?.locked, false);
+  }
+});
+
+test("readBoundedText limits decoded gzip bytes, not the compressed length", async () => {
+  const compressed = gzipSync('"' + "a".repeat(4096) + '"');
+  ok(compressed.length < 128);
+  const decoded = gunzipSync(compressed);
+  await rejects(
+    readBoundedText(
+      new Response(decoded, {
+        headers: {
+          "Content-Encoding": "gzip",
+          "Content-Length": String(compressed.length),
+        },
+      }),
+      128,
+      url,
+    ),
+    BodyTooLargeError,
+  );
+  // The encoded representation can also be larger than a valid decoded body.
+  deepStrictEqual(
+    await readBoundedText(
+      new Response("{}", {
+        headers: { "Content-Encoding": "gzip", "Content-Length": "22" },
+      }),
+      2,
+      url,
+    ),
+    "{}",
+  );
+});
+
+test("readBoundedText rejects invalid limits and releases failed streams", async () => {
+  for (const limit of [0, -1, NaN, Infinity, 1.5]) {
+    await rejects(readBoundedText(new Response("{}"), limit, url), RangeError);
+  }
+  const failure = new Error("broken stream");
+  const response = new Response(
+    new ReadableStream({
+      pull(controller) {
+        controller.error(failure);
+      },
+    }),
+  );
+  await rejects(
+    readBoundedText(response, 10, url),
+    (error) => error === failure,
+  );
+  deepStrictEqual(response.body?.locked, false);
+});

package/src/body.ts

@@ -0,0 +1,152 @@
+// Kept private in each package to avoid adding public API in a patch release.
+// TODO(Jiwon Kwon): Consolidate the duplicated body helpers in @fedify/vocab-runtime,
+// @fedify/webfinger, and @fedify/fedify into a shared implementation.
+import { getLogger } from "@logtape/logtape";
+import { FetchError } from "./request.ts";
+
+/** Decoded JSON body limit: 16 MiB.  @internal */
+export const MAX_BODY_SIZE: number = 16 * 1024 * 1024;
+
+/** A body exceeded the byte limit.  @internal */
+export class BodyTooLargeError extends FetchError {
+  /** Creates an error for a body exceeding the given limit. */
+  constructor(url: string | URL, maxBytes: number) {
+    super(url, `Body exceeds the limit of ${maxBytes} bytes`);
+    this.name = "BodyTooLargeError";
+  }
+}
+
+/** Validates a finite, positive byte limit.  @internal */
+function validateBodySizeLimit(maxBytes: number): void {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new RangeError(
+      "The body size limit must be a positive safe integer.",
+    );
+  }
+}
+
+/**
+ * Reads UTF-8 text while limiting bytes received from the body stream.
+ * Fetch responses are already decompressed, so the stream count is authoritative.
+ * @param message The response or request to read.
+ * @param maxBytes The maximum number of decoded bytes to read.
+ * @param url The URL to include in errors and logs.
+ * @returns The decoded body text.
+ * @throws {BodyTooLargeError} If the body exceeds the limit.
+ * @internal
+ */
+export async function readBoundedText(
+  message: Pick<Request, "body" | "headers">,
+  maxBytes: number,
+  url: string | URL,
+): Promise<string> {
+  validateBodySizeLimit(maxBytes);
+  const reader = message.body?.getReader();
+  const tooLarge = (): never => {
+    getLogger(["fedify", "runtime", "body"]).warn(
+      "Body from {url} exceeds the limit of {maxBytes} bytes.",
+      { url: url.toString(), maxBytes },
+    );
+    throw new BodyTooLargeError(url, maxBytes);
+  };
+  try {
+    // Content-Length describes the encoded body when compression is used.
+    // Only use it as an early rejection for an unencoded body.
+    const length = message.headers.get("Content-Length");
+    const encoding = message.headers.get("Content-Encoding");
+    if (
+      (encoding == null || encoding.toLowerCase() === "identity") &&
+      length != null && /^\d+$/.test(length) && Number(length) > maxBytes
+    ) tooLarge();
+    if (reader == null) return "";
+    let size = 0;
+    const bounded = new ReadableStream<BufferSource>({
+      async pull(controller) {
+        const { done, value } = await reader.read();
+        if (done) {
+          controller.close();
+          return;
+        }
+        size += value.byteLength;
+        if (size > maxBytes) tooLarge();
+        controller.enqueue(value);
+      },
+    }, { highWaterMark: 0 });
+    const textReader = bounded.pipeThrough(new TextDecoderStream()).getReader();
+    try {
+      const chunks: string[] = [];
+      while (true) {
+        const { done, value } = await textReader.read();
+        if (done) break;
+        chunks.push(value);
+      }
+      return chunks.join("");
+    } finally {
+      textReader.releaseLock();
+    }
+  } catch (error) {
+    // A cloned inbox request is a tee.  Awaiting one branch's cancellation
+    // would deadlock until the other branch is canceled by the inbox handler.
+    if (reader != null) void reader.cancel(error).catch(() => {});
+    throw error;
+  } finally {
+    reader?.releaseLock();
+  }
+}
+
+/**
+ * Reads raw bytes while limiting bytes received from the body stream.
+ * Unlike {@link readBoundedText}, the bytes are returned as they were
+ * received, without decoding.
+ * @param message The response or request to read.
+ * @param maxBytes The maximum number of decoded bytes to read.
+ * @param url The URL to include in errors and logs.
+ * @returns The body bytes.
+ * @throws {BodyTooLargeError} If the body exceeds the limit.
+ * @internal
+ */
+export async function readBoundedBytes(
+  message: Pick<Request, "body" | "headers">,
+  maxBytes: number,
+  url: string | URL,
+): Promise<Uint8Array<ArrayBuffer>> {
+  validateBodySizeLimit(maxBytes);
+  const reader = message.body?.getReader();
+  const tooLarge = (): never => {
+    getLogger(["fedify", "runtime", "body"]).warn(
+      "Body from {url} exceeds the limit of {maxBytes} bytes.",
+      { url: url.toString(), maxBytes },
+    );
+    throw new BodyTooLargeError(url, maxBytes);
+  };
+  try {
+    const length = message.headers.get("Content-Length");
+    const encoding = message.headers.get("Content-Encoding");
+    if (
+      (encoding == null || encoding.toLowerCase() === "identity") &&
+      length != null && /^\d+$/.test(length) && Number(length) > maxBytes
+    ) tooLarge();
+    if (reader == null) return new Uint8Array(0);
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > maxBytes) tooLarge();
+      chunks.push(value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return bytes;
+  } catch (error) {
+    if (reader != null) void reader.cancel(error).catch(() => {});
+    throw error;
+  } finally {
+    reader?.releaseLock();
+  }
+}

package/src/contexts/cid-v1.json

@@ -0,0 +1,114 @@
+{
+  "@context": {
+    "@protected": true,
+    "id": "@id",
+    "type": "@type",
+
+    "alsoKnownAs": {
+      "@id": "https://www.w3.org/ns/activitystreams#alsoKnownAs",
+      "@type": "@id"
+    },
+    "assertionMethod": {
+      "@id": "https://w3id.org/security#assertionMethod",
+      "@type": "@id",
+      "@container": "@set"
+    },
+    "authentication": {
+      "@id": "https://w3id.org/security#authenticationMethod",
+      "@type": "@id",
+      "@container": "@set"
+    },
+    "capabilityDelegation": {
+      "@id": "https://w3id.org/security#capabilityDelegationMethod",
+      "@type": "@id",
+      "@container": "@set"
+    },
+    "capabilityInvocation": {
+      "@id": "https://w3id.org/security#capabilityInvocationMethod",
+      "@type": "@id",
+      "@container": "@set"
+    },
+    "controller": {
+      "@id": "https://w3id.org/security#controller",
+      "@type": "@id"
+    },
+    "keyAgreement": {
+      "@id": "https://w3id.org/security#keyAgreementMethod",
+      "@type": "@id",
+      "@container": "@set"
+    },
+    "service": {
+      "@id": "https://www.w3.org/ns/did#service",
+      "@type": "@id",
+      "@context": {
+        "@protected": true,
+        "id": "@id",
+        "type": "@type",
+        "serviceEndpoint": {
+          "@id": "https://www.w3.org/ns/did#serviceEndpoint",
+          "@type": "@id"
+        }
+      }
+    },
+    "verificationMethod": {
+      "@id": "https://w3id.org/security#verificationMethod",
+      "@type": "@id"
+    },
+    "Multikey": {
+      "@id": "https://w3id.org/security#Multikey",
+      "@context": {
+        "@protected": true,
+        "id": "@id",
+        "type": "@type",
+        "controller": {
+          "@id": "https://w3id.org/security#controller",
+          "@type": "@id"
+        },
+        "revoked": {
+          "@id": "https://w3id.org/security#revoked",
+          "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
+        },
+        "expires": {
+          "@id": "https://w3id.org/security#expiration",
+          "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
+        },
+        "publicKeyMultibase": {
+          "@id": "https://w3id.org/security#publicKeyMultibase",
+          "@type": "https://w3id.org/security#multibase"
+        },
+        "secretKeyMultibase": {
+          "@id": "https://w3id.org/security#secretKeyMultibase",
+          "@type": "https://w3id.org/security#multibase"
+        }
+      }
+    },
+    "JsonWebKey": {
+      "@id": "https://w3id.org/security#JsonWebKey",
+      "@context": {
+        "@protected": true,
+        "id": "@id",
+        "type": "@type",
+        "controller": {
+          "@id": "https://w3id.org/security#controller",
+          "@type": "@id"
+        },
+        "revoked": {
+          "@id": "https://w3id.org/security#revoked",
+          "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
+        },
+        "expires": {
+          "@id": "https://w3id.org/security#expiration",
+          "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
+        },
+        "publicKeyJwk": {
+          "@id": "https://w3id.org/security#publicKeyJwk",
+          "@type": "@json"
+        },
+        "secretKeyJwk": {
+          "@id": "https://w3id.org/security#secretKeyJwk",
+          "@type": "@json"
+        }
+      }
+    }
+  }
+}

package/src/contexts/fep-22cd.json

@@ -0,0 +1,21 @@
+{
+  "@context": {
+    "fep-22cd": "https://w3id.org/fep/22cd#",
+    "schema": "https://schema.org/",
+    "xsd": "http://www.w3.org/2001/XMLSchema#",
+    "translations": { "@id": "fep-22cd:translations", "@container": "@set" },
+    "Translation": "fep-22cd:Translation",
+    "sourceUpdated": {
+      "@id": "fep-22cd:sourceUpdated",
+      "@type": "xsd:dateTime"
+    },
+    "translator": {
+      "@id": "schema:translator",
+      "@type": "@id",
+      "@container": "@set"
+    },
+    "inLanguage": "schema:inLanguage",
+    "translationOfWork": { "@id": "schema:translationOfWork", "@type": "@id" },
+    "isBasedOn": { "@id": "schema:isBasedOn", "@type": "@id" }
+  }
+}

package/src/contexts/miscellany.json

@@ -0,0 +1,17 @@
+{
+  "@context": {
+    "as": "https://www.w3.org/ns/activitystreams#",
+    "xsd": "http://www.w3.org/2001/XMLSchema#",
+    "Hashtag": "as:Hashtag",
+    "manuallyApprovesFollowers": {
+      "@id": "as:manuallyApprovesFollowers"
+    },
+    "movedTo": {
+      "@id": "as:movedTo",
+      "@type": "@id"
+    },
+    "sensitive": {
+      "@id": "as:sensitive"
+    }
+  }
+}

package/src/contexts.ts

@@ -5,7 +5,9 @@
 import activitystreams from "./contexts/activitystreams.json" with {
   type: "json",
 };
+import cidV1Context from "./contexts/cid-v1.json" with { type: "json" };
 import didV1 from "./contexts/did-v1.json" with { type: "json" };
+import fep22cd from "./contexts/fep-22cd.json" with { type: "json" };
 import fep5711 from "./contexts/fep-5711.json" with { type: "json" };
 import fep7aa9 from "./contexts/fep-7aa9.json" with { type: "json" };
 import fepEf61 from "./contexts/fep-ef61.json" with { type: "json" };
@@ -13,6 +15,7 @@ import gotosocial from "./contexts/gotosocial.json" with { type: "json" };
 import identityV1 from "./contexts/identity-v1.json" with { type: "json" };
 import joinLemmyContext from "./contexts/join-lemmy.json" with { type: "json" };
 import joinmastodon from "./contexts/joinmastodon.json" with { type: "json" };
+import miscellany from "./contexts/miscellany.json" with { type: "json" };
 import schemaorg from "./contexts/schemaorg.json" with { type: "json" };
 import securityDataIntegrityV1 from "./contexts/security-data-integrity-v1.json" with {
   type: "json",
@@ -36,10 +39,33 @@ const preloadedContexts: Record<string, unknown> = {
   "https://purl.archive.org/socialweb/webfinger": webfinger,
   "http://schema.org/": schemaorg,
   "https://gotosocial.org/ns": gotosocial,
+  "https://w3id.org/fep/22cd": fep22cd,
   "https://w3id.org/fep/5711": fep5711,
-  "https://w3id.org/fep/7aa9": fep7aa9,
+
+  // Controlled Identifiers v1.0 requires JSON-LD processors to treat this
+  // context URL as already resolved.  We ship the official W3C context so that
+  // controlled identifier documents can be processed without depending on the
+  // availability of the remote context server.
+  // See: https://www.w3.org/TR/cid-1.0/#json-ld-context
+  //      https://github.com/fedify-dev/fedify/issues/932
+  "https://www.w3.org/ns/cid/v1": cidV1Context,
+
+  // The FEP-ef61 context.  The w3id.org URL redirects to Codeberg Pages, which
+  // suffers recurring outages; while it is unreachable, every document
+  // referencing this URL fails JSON-LD expansion before application handlers
+  // run.  We ship a built-in copy so that portable objects can be processed
+  // without depending on the availability of the remote context server.
+  // See: https://w3id.org/fep/ef61
+  //      https://github.com/fedify-dev/fedify/issues/982
   "https://w3id.org/fep/ef61": fepEf61,
 
+  // The FEP-7aa9 context is hosted on Codeberg Pages, whose outages can
+  // prevent actor documents from being parsed.  Resolve it locally so that
+  // parsing does not depend on the remote context server's availability.
+  // See: https://w3id.org/fep/7aa9
+  //      https://github.com/fedify-dev/fedify/issues/1078
+  "https://w3id.org/fep/7aa9": fep7aa9,
+
   // Lemmy's context document is served as application/json without the JSON-LD
   // context Link header.  The default document loader treats that as a regular
   // JSON response instead of a JSON-LD context, so every Lemmy activity that
@@ -59,6 +85,18 @@ const preloadedContexts: Record<string, unknown> = {
   // See: https://github.com/mastodon/joinmastodon/issues/148
   //      https://github.com/fedify-dev/fedify/issues/630
   "http://joinmastodon.org/ns": joinmastodon,
+
+  // The SWICG "ActivityPub Miscellaneous Terms" context.  Bridgy Fed (via
+  // granary) references this URL in the @context of every activity it sends,
+  // and other implementations use it as the recommended home for widely
+  // deployed extension terms like as:Hashtag and as:sensitive.  It is served
+  // through purl.archive.org (Internet Archive's PURL service), which suffers
+  // recurring outages; while it is unreachable, every activity referencing
+  // this URL fails JSON-LD expansion before application handlers run.  The
+  // document is a deliberately stable, versioned SWICG deliverable, so we
+  // ship a built-in copy.
+  // See: https://swicg.github.io/miscellany/
+  "https://purl.archive.org/miscellany": miscellany,
 };
 
 export default preloadedContexts;