@fedify/vocab-runtime 2.4.0-dev.1618 → 2.4.0-dev.1655

package/src/contexts/security-data-integrity-v1.json

@@ -3,10 +3,6 @@
     "id": "@id",
     "type": "@type",
     "@protected": true,
-    "digestMultibase": {
-      "@id": "https://w3id.org/security#digestMultibase",
-      "@type": "https://w3id.org/security#multibase"
-    },
     "proof": {
       "@id": "https://w3id.org/security#proof",
       "@type": "@id",

package/src/contexts.ts

@@ -8,6 +8,7 @@ import activitystreams from "./contexts/activitystreams.json" with {
 import didV1 from "./contexts/did-v1.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" };
 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" };
@@ -37,6 +38,7 @@ const preloadedContexts: Record<string, unknown> = {
   "https://gotosocial.org/ns": gotosocial,
   "https://w3id.org/fep/5711": fep5711,
   "https://w3id.org/fep/7aa9": fep7aa9,
+  "https://w3id.org/fep/ef61": fepEf61,
 
   // 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

package/src/digest.test.ts

@@ -0,0 +1,220 @@
+import { deepStrictEqual, equal, rejects, throws } from "node:assert/strict";
+import { test } from "node:test";
+import { addMulticodecPrefix } from "./internal/multicodec.ts";
+import { encodeMultibase } from "./multibase/mod.ts";
+import {
+  computeDigestMultibase,
+  createHashlink,
+  parseDigestMultibase,
+  parseHashlink,
+  verifyDigestMultibase,
+  verifyHashlink,
+} from "./digest.ts";
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const bytes = encoder.encode("Hello World!");
+// Test vector from draft-sporny-hashlink-07, appendix B.1.
+const digestMultibase = "zQmWvQxTqbG2Z9HPJgG57jjwR154cKhbtJenbyYTWkjgF3e";
+const hashlink = `hl:${digestMultibase}`;
+
+test("computeDigestMultibase() computes a SHA-256 multihash", async () => {
+  equal(await computeDigestMultibase(bytes), digestMultibase);
+  const parsed = parseDigestMultibase(digestMultibase);
+  equal(parsed.algorithm, "sha2-256");
+  deepStrictEqual(
+    parsed.digest,
+    new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)),
+  );
+});
+
+test("digest helpers accept SharedArrayBuffer-backed bytes", async () => {
+  const sharedBytes = new Uint8Array(new SharedArrayBuffer(bytes.length));
+  sharedBytes.set(bytes);
+  Object.defineProperty(sharedBytes, "slice", {
+    value: () => {
+      throw new Error("Shared input must not be copied with slice().");
+    },
+  });
+  equal(await computeDigestMultibase(sharedBytes), digestMultibase);
+  equal(await verifyDigestMultibase(sharedBytes, digestMultibase), true);
+});
+
+test("digest helpers ignore spoofed shared buffer tags", async () => {
+  const taggedBytes = bytes.slice();
+  Object.defineProperty(taggedBytes.buffer, Symbol.toStringTag, {
+    value: "SharedArrayBuffer",
+  });
+  Object.defineProperty(taggedBytes, "slice", {
+    value: () => {
+      throw new Error("ArrayBuffer input must not be copied.");
+    },
+  });
+  equal(await computeDigestMultibase(taggedBytes), digestMultibase);
+  equal(await verifyDigestMultibase(taggedBytes, digestMultibase), true);
+});
+
+test("createHashlink() and parseHashlink() round-trip simple hashlinks", () => {
+  equal(createHashlink(digestMultibase), hashlink);
+  deepStrictEqual(parseHashlink(hashlink), { digestMultibase });
+  deepStrictEqual(parseHashlink(new URL(hashlink)), { digestMultibase });
+
+  const base64DigestMultibase = decoder.decode(
+    encodeMultibase(
+      "base64",
+      addMulticodecPrefix(
+        0x12,
+        addMulticodecPrefix(32, new Uint8Array(32).fill(0xff)),
+      ),
+    ),
+  );
+  const base64Hashlink = createHashlink(base64DigestMultibase);
+  equal(
+    base64Hashlink,
+    "hl:mEiD//////////////////////////////////////////w",
+  );
+  deepStrictEqual(parseHashlink(base64Hashlink), {
+    digestMultibase: base64DigestMultibase,
+  });
+  deepStrictEqual(parseHashlink(new URL(base64Hashlink)), {
+    digestMultibase: base64DigestMultibase,
+  });
+});
+
+test("digest and hashlink verification accepts matching bytes", async () => {
+  equal(await verifyDigestMultibase(bytes, digestMultibase), true);
+  equal(await verifyHashlink(bytes, hashlink), true);
+  equal(await verifyHashlink(bytes, new URL(hashlink)), true);
+});
+
+test("digest and hashlink verification rejects non-matching bytes", async () => {
+  const different = encoder.encode("Hello World?");
+  equal(await verifyDigestMultibase(different, digestMultibase), false);
+  equal(await verifyHashlink(different, hashlink), false);
+});
+
+test("parseDigestMultibase() rejects unsupported algorithms", () => {
+  const sha1Multihash = addMulticodecPrefix(
+    0x11,
+    addMulticodecPrefix(20, new Uint8Array(20)),
+  );
+  const value = decoder.decode(encodeMultibase("base58btc", sha1Multihash));
+  throws(
+    () => parseDigestMultibase(value),
+    new TypeError("Unsupported digest algorithm: 0x11"),
+  );
+});
+
+test("parseDigestMultibase() rejects malformed values", async () => {
+  throws(
+    () => parseDigestMultibase("not-multibase"),
+    new TypeError("Invalid digestMultibase encoding."),
+  );
+
+  const missingLength = decoder.decode(
+    encodeMultibase("base58btc", Uint8Array.of(0x12)),
+  );
+  throws(
+    () => parseDigestMultibase(missingLength),
+    new TypeError("Invalid digestMultibase multihash."),
+  );
+
+  const multihash = addMulticodecPrefix(
+    0x12,
+    addMulticodecPrefix(32, new Uint8Array(32)),
+  );
+  const base2 = decoder.decode(encodeMultibase("base2", multihash));
+  equal(base2.length, 273);
+  deepStrictEqual(parseDigestMultibase(base2).digest, new Uint8Array(32));
+  throws(
+    () => parseDigestMultibase(`${base2}0`),
+    new TypeError("Invalid digestMultibase encoding."),
+  );
+
+  const padded = decoder.decode(encodeMultibase("base64pad", multihash));
+  equal(padded.endsWith("=="), true);
+  deepStrictEqual(parseDigestMultibase(padded).digest, new Uint8Array(32));
+  throws(
+    () => parseDigestMultibase(padded.slice(0, -1)),
+    new TypeError("Invalid digestMultibase encoding."),
+  );
+  throws(
+    () => createHashlink(`${padded}=`),
+    new TypeError("Invalid digestMultibase encoding."),
+  );
+
+  const overlongAlgorithm = decoder.decode(
+    encodeMultibase(
+      "base58btc",
+      Uint8Array.of(0x92, 0x00, 0x20, ...new Uint8Array(32)),
+    ),
+  );
+  throws(
+    () => parseDigestMultibase(overlongAlgorithm),
+    new TypeError("Invalid digestMultibase multihash."),
+  );
+
+  const overlongLength = decoder.decode(
+    encodeMultibase(
+      "base58btc",
+      Uint8Array.of(0x12, 0xa0, 0x00, ...new Uint8Array(32)),
+    ),
+  );
+  throws(
+    () => parseDigestMultibase(overlongLength),
+    new TypeError("Invalid digestMultibase multihash."),
+  );
+
+  const shortDigest = decoder.decode(
+    encodeMultibase(
+      "base58btc",
+      addMulticodecPrefix(0x12, addMulticodecPrefix(31, new Uint8Array(31))),
+    ),
+  );
+  throws(
+    () => parseDigestMultibase(shortDigest),
+    new TypeError("Invalid SHA-256 digest length."),
+  );
+  await rejects(
+    () => verifyDigestMultibase(bytes, shortDigest),
+    new TypeError("Invalid SHA-256 digest length."),
+  );
+});
+
+test("simple hashlink helpers reject metadata and malformed forms", async () => {
+  for (const terminator of ["\n", "\r", "\r\n", "\u2028", "\u2029"]) {
+    const malformedHashlink = `${hashlink}${terminator}`;
+    throws(
+      () => parseHashlink(malformedHashlink),
+      new TypeError("Invalid simple hashlink."),
+    );
+    await rejects(
+      () => verifyHashlink(bytes, malformedHashlink),
+      new TypeError("Invalid simple hashlink."),
+    );
+  }
+  throws(
+    () => parseHashlink(`${hashlink}:zmetadata`),
+    new TypeError("Invalid simple hashlink."),
+  );
+  await rejects(
+    () => verifyHashlink(bytes, `${hashlink}:zmetadata`),
+    new TypeError("Invalid simple hashlink."),
+  );
+  throws(
+    () => parseHashlink(`https://example.com/file?hl=${digestMultibase}`),
+    new TypeError("Invalid simple hashlink."),
+  );
+  throws(
+    () => parseHashlink("hl:not-multibase"),
+    new TypeError("Invalid digestMultibase encoding."),
+  );
+  await rejects(
+    () => verifyHashlink(bytes, "hl:not-multibase"),
+    new TypeError("Invalid digestMultibase encoding."),
+  );
+  throws(
+    () => createHashlink("not-multibase"),
+    new TypeError("Invalid digestMultibase encoding."),
+  );
+});

package/src/digest.ts

@@ -0,0 +1,229 @@
+import {
+  addMulticodecPrefix,
+  getMulticodecPrefix,
+} from "./internal/multicodec.ts";
+import {
+  decodeMultibase,
+  encodeMultibase,
+  encodingFromBaseData,
+} from "./multibase/mod.ts";
+
+const SHA2_256_MULTIHASH_CODE = 0x12;
+const SHA2_256_DIGEST_LENGTH = 32;
+const MAX_DIGEST_MULTIBASE_LENGTH = 1 + (SHA2_256_DIGEST_LENGTH + 2) * 8;
+const textDecoder = new TextDecoder();
+const getArrayBufferByteLength = Object.getOwnPropertyDescriptor(
+  ArrayBuffer.prototype,
+  "byteLength",
+)?.get;
+
+function isCanonicalVarintPrefix(
+  data: Uint8Array,
+  prefix: ReturnType<typeof getMulticodecPrefix>,
+): boolean {
+  const canonical = addMulticodecPrefix(prefix.code, new Uint8Array());
+  if (canonical.length !== prefix.prefixLength) return false;
+  for (let i = 0; i < canonical.length; i++) {
+    if (data[i] !== canonical[i]) return false;
+  }
+  return true;
+}
+
+function toWebCryptoBytes(bytes: Uint8Array): Uint8Array<ArrayBuffer> {
+  if (getArrayBufferByteLength != null) {
+    try {
+      getArrayBufferByteLength.call(bytes.buffer);
+      return bytes as Uint8Array<ArrayBuffer>;
+    } catch {
+      // SharedArrayBuffer input needs to be copied for Web Crypto.
+    }
+  }
+  return new Uint8Array(bytes);
+}
+
+/**
+ * A parsed SHA-256 resource digest.
+ *
+ * @since 2.4.0
+ */
+export interface ParsedDigestMultibase {
+  /** The multihash algorithm represented by the digest. */
+  readonly algorithm: "sha2-256";
+
+  /** The raw 32-byte SHA-256 digest. */
+  readonly digest: Uint8Array;
+}
+
+/**
+ * A parsed simple hashlink.
+ *
+ * @since 2.4.0
+ */
+export interface ParsedHashlink {
+  /** The multibase-encoded multihash carried by the hashlink. */
+  readonly digestMultibase: string;
+}
+
+/**
+ * Computes the SHA-256 digest of a byte sequence and encodes it as a
+ * base58-btc multibase multihash suitable for FEP-ef61's
+ * `digestMultibase` property.
+ *
+ * @param bytes The bytes to digest.
+ * @returns The base58-btc multibase-encoded SHA-256 multihash.
+ * @since 2.4.0
+ */
+export async function computeDigestMultibase(
+  bytes: Uint8Array,
+): Promise<string> {
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", toWebCryptoBytes(bytes)),
+  );
+  const lengthAndDigest = addMulticodecPrefix(digest.length, digest);
+  const multihash = addMulticodecPrefix(
+    SHA2_256_MULTIHASH_CODE,
+    lengthAndDigest,
+  );
+  return textDecoder.decode(encodeMultibase("base58btc", multihash));
+}
+
+/**
+ * Parses and validates a SHA-256 `digestMultibase` value.
+ *
+ * @param value The multibase-encoded multihash to parse.
+ * @returns The digest algorithm and raw digest bytes.
+ * @throws {TypeError} If the value is malformed or uses an unsupported hash
+ *                      algorithm.
+ * @since 2.4.0
+ */
+export function parseDigestMultibase(value: string): ParsedDigestMultibase {
+  if (value.length > MAX_DIGEST_MULTIBASE_LENGTH) {
+    throw new TypeError("Invalid digestMultibase encoding.");
+  }
+  let multihash: Uint8Array;
+  try {
+    multihash = decodeMultibase(value);
+  } catch (error) {
+    throw new TypeError("Invalid digestMultibase encoding.", { cause: error });
+  }
+  const encoding = encodingFromBaseData(value);
+  const canonicalValue = textDecoder.decode(
+    encodeMultibase(encoding.name, multihash),
+  );
+  if (value !== canonicalValue) {
+    throw new TypeError("Invalid digestMultibase encoding.");
+  }
+
+  let algorithmPrefix: ReturnType<typeof getMulticodecPrefix>;
+  try {
+    algorithmPrefix = getMulticodecPrefix(multihash);
+  } catch (error) {
+    throw new TypeError("Invalid digestMultibase multihash.", { cause: error });
+  }
+  if (!isCanonicalVarintPrefix(multihash, algorithmPrefix)) {
+    throw new TypeError("Invalid digestMultibase multihash.");
+  }
+  if (algorithmPrefix.code !== SHA2_256_MULTIHASH_CODE) {
+    throw new TypeError(
+      `Unsupported digest algorithm: 0x${algorithmPrefix.code.toString(16)}`,
+    );
+  }
+
+  const lengthAndDigest = multihash.subarray(algorithmPrefix.prefixLength);
+  let lengthPrefix: ReturnType<typeof getMulticodecPrefix>;
+  try {
+    lengthPrefix = getMulticodecPrefix(lengthAndDigest);
+  } catch (error) {
+    throw new TypeError("Invalid digestMultibase multihash.", { cause: error });
+  }
+  if (!isCanonicalVarintPrefix(lengthAndDigest, lengthPrefix)) {
+    throw new TypeError("Invalid digestMultibase multihash.");
+  }
+  const digest = lengthAndDigest.slice(lengthPrefix.prefixLength);
+  if (
+    lengthPrefix.code !== SHA2_256_DIGEST_LENGTH ||
+    digest.length !== SHA2_256_DIGEST_LENGTH
+  ) {
+    throw new TypeError("Invalid SHA-256 digest length.");
+  }
+  return { algorithm: "sha2-256", digest };
+}
+
+function extractDigestMultibase(value: string | URL): string {
+  const hashlink = typeof value === "string" ? value : value.href;
+  const match = /^hl:([^:\r\n\u2028\u2029]+)$/i.exec(hashlink);
+  if (match == null || match[0].length !== hashlink.length) {
+    throw new TypeError("Invalid simple hashlink.");
+  }
+  return match[1];
+}
+
+/**
+ * Parses a metadata-free `hl:` hashlink and validates its resource digest.
+ *
+ * @param value The simple hashlink to parse.
+ * @returns The `digestMultibase` value carried by the hashlink.
+ * @throws {TypeError} If the hashlink is malformed, contains metadata, or
+ *                      carries an invalid or unsupported digest.
+ * @since 2.4.0
+ */
+export function parseHashlink(value: string | URL): ParsedHashlink {
+  const digestMultibase = extractDigestMultibase(value);
+  parseDigestMultibase(digestMultibase);
+  return { digestMultibase };
+}
+
+/**
+ * Creates a metadata-free `hl:` hashlink from a `digestMultibase` value.
+ *
+ * @param digestMultibase The SHA-256 multibase multihash to embed.
+ * @returns The simple hashlink.
+ * @throws {TypeError} If the digest is malformed or unsupported.
+ * @since 2.4.0
+ */
+export function createHashlink(digestMultibase: string): string {
+  parseDigestMultibase(digestMultibase);
+  return `hl:${digestMultibase}`;
+}
+
+/**
+ * Verifies that bytes match a SHA-256 `digestMultibase` value.
+ *
+ * @param bytes The bytes to verify.
+ * @param digestMultibase The expected digest.
+ * @returns Whether the bytes match the digest.
+ * @throws {TypeError} If the digest is malformed or unsupported.
+ * @since 2.4.0
+ */
+export async function verifyDigestMultibase(
+  bytes: Uint8Array,
+  digestMultibase: string,
+): Promise<boolean> {
+  const expected = parseDigestMultibase(digestMultibase).digest;
+  const actual = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", toWebCryptoBytes(bytes)),
+  );
+  if (expected.length !== actual.length) return false;
+  let difference = 0;
+  for (let i = 0; i < expected.length; i++) {
+    difference |= expected[i] ^ actual[i];
+  }
+  return difference === 0;
+}
+
+/**
+ * Verifies that bytes match the resource digest in a simple hashlink.
+ *
+ * @param bytes The bytes to verify.
+ * @param hashlink The simple hashlink containing the expected digest.
+ * @returns Whether the bytes match the hashlink digest.
+ * @throws {TypeError} If the hashlink or digest is malformed or unsupported.
+ * @since 2.4.0
+ */
+export async function verifyHashlink(
+  bytes: Uint8Array,
+  hashlink: string | URL,
+): Promise<boolean> {
+  const digestMultibase = extractDigestMultibase(hashlink);
+  return await verifyDigestMultibase(bytes, digestMultibase);
+}

package/src/docloader.ts

@@ -351,8 +351,10 @@ export interface GetDocumentLoaderOptions extends DocumentLoaderFactoryOptions {
  * - <https://www.w3.org/ns/activitystreams>
  * - <https://w3id.org/security/v1>
  * - <https://w3id.org/security/data-integrity/v1>
+ * - <https://w3id.org/security/data-integrity/v2>
  * - <https://www.w3.org/ns/did/v1>
  * - <https://w3id.org/security/multikey/v1>
+ * - <https://w3id.org/fep/ef61>
  * - <https://purl.archive.org/socialweb/webfinger>
  * - <http://schema.org/>
  * @param options Options for the document loader.

package/src/mod.ts

@@ -34,6 +34,16 @@ export {
   isDecimal,
   parseDecimal,
 } from "./decimal.ts";
+export {
+  computeDigestMultibase,
+  createHashlink,
+  type ParsedDigestMultibase,
+  type ParsedHashlink,
+  parseDigestMultibase,
+  parseHashlink,
+  verifyDigestMultibase,
+  verifyHashlink,
+} from "./digest.ts";
 export { LanguageString } from "./langstr.ts";
 export {
   decodeMultibase,
@@ -61,8 +71,10 @@ export {
   getFe34Origin,
   haveSameFe34Origin,
   haveSameIriOrigin,
+  isGatewayUrl,
   isValidPublicIPv4Address,
   isValidPublicIPv6Address,
+  parseGatewayUrl,
   parseIri,
   parseJsonLdId,
   UrlError,

package/src/url.test.ts

@@ -8,8 +8,10 @@ import {
   getFe34Origin,
   haveSameFe34Origin,
   haveSameIriOrigin,
+  isGatewayUrl,
   isValidPublicIPv4Address,
   isValidPublicIPv6Address,
+  parseGatewayUrl,
   parseIri,
   parseJsonLdId,
   UrlError,
@@ -638,6 +640,27 @@ test("parseIri() preserves encoded percent signs while decoding delimiters", ()
   );
 });
 
+test("parseGatewayUrl() accepts only HTTP(S) base URIs", () => {
+  for (const url of ["https://server.example/", "http://server.example/"]) {
+    deepStrictEqual(parseGatewayUrl(url), new URL(url));
+    ok(isGatewayUrl(new URL(url)));
+  }
+
+  for (
+    const url of [
+      "ftp://server.example/",
+      "https://user:pass@server.example/",
+      "https://user@server.example/",
+      "https://server.example/path",
+      "https://server.example/?x=1",
+      "https://server.example/#fragment",
+    ]
+  ) {
+    throws(() => parseGatewayUrl(url), TypeError);
+    ok(!isGatewayUrl(new URL(url)));
+  }
+});
+
 test("validatePublicUrl()", async () => {
   await rejects(() => validatePublicUrl("ftp://localhost"), UrlError);
   await rejects(

package/src/url.ts

@@ -323,6 +323,29 @@ function parseAtUri(uri: string): URL {
   return new URL("at://" + encodeURIComponent(authority) + path);
 }
 
+/**
+ * Checks whether the URL is an FEP-ef61 gateway base URI.
+ */
+export function isGatewayUrl(url: URL): boolean {
+  return (url.protocol === "http:" || url.protocol === "https:") &&
+    url.username === "" && url.password === "" &&
+    url.pathname === "/" && url.search === "" && url.hash === "";
+}
+
+/**
+ * Parses and validates an FEP-ef61 gateway base URI.
+ */
+export function parseGatewayUrl(url: string): URL {
+  const parsed = parseIri(url);
+  if (!isGatewayUrl(parsed)) {
+    throw new TypeError(
+      "FEP-ef61 gateways must be HTTP(S) base URIs with no credentials, " +
+        "path, query, or fragment.",
+    );
+  }
+  return parsed;
+}
+
 /**
  * Validates a URL to prevent SSRF attacks.
  */