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

package/dist/tests/{multibase-B4bvakyA.mjs → multibase-Cluwl8OM.mjs}

@@ -303,5 +303,16 @@ function encoding(nameOrCode) {
 	else if (Object.prototype.hasOwnProperty.call(codes, nameOrCode)) return codes[nameOrCode];
 	else throw new Error(`Unsupported encoding: ${nameOrCode}`);
 }
+/**
+* Get encoding multibase from data
+*
+* @param {string|Uint8Array} data
+* @returns {Base}
+* @throws {Error} Will throw if the encoding is not supported
+*/
+function encodingFromBaseData(data) {
+	if (data instanceof Uint8Array) data = decodeText(data);
+	return encoding(data[0]);
+}
 //#endregion
-export { decodeText as a, names as i, encodeMultibase as n, encodeText as o, codes as r, decodeMultibase as t };
+export { names as a, codes as i, encodeMultibase as n, decodeText as o, encodingFromBaseData as r, encodeText as s, decodeMultibase as t };

package/dist/tests/{multibase-Bz_UUDtL.cjs → multibase-DcDQDNnI.cjs}

@@ -305,6 +305,17 @@ function encoding(nameOrCode) {
 	else if (Object.prototype.hasOwnProperty.call(codes, nameOrCode)) return codes[nameOrCode];
 	else throw new Error(`Unsupported encoding: ${nameOrCode}`);
 }
+/**
+* Get encoding multibase from data
+*
+* @param {string|Uint8Array} data
+* @returns {Base}
+* @throws {Error} Will throw if the encoding is not supported
+*/
+function encodingFromBaseData(data) {
+	if (data instanceof Uint8Array) data = decodeText(data);
+	return encoding(data[0]);
+}
 //#endregion
 Object.defineProperty(exports, "codes", {
 	enumerable: true,
@@ -336,6 +347,12 @@ Object.defineProperty(exports, "encodeText", {
 		return encodeText;
 	}
 });
+Object.defineProperty(exports, "encodingFromBaseData", {
+	enumerable: true,
+	get: function() {
+		return encodingFromBaseData;
+	}
+});
 Object.defineProperty(exports, "names", {
 	enumerable: true,
 	get: function() {

package/dist/tests/{request-BWDludWb.mjs → request-B6s_F7bi.mjs}

@@ -1,7 +1,7 @@
 import process from "node:process";
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.4.0-dev.1634+3b4bfbb6";
+var version = "2.4.0-dev.1655+b8f3c3d5";
 //#endregion
 //#region src/request.ts
 /**

package/dist/tests/{request-Zpjq9m-W.cjs → request-DvEyU5Zf.cjs}

@@ -3,7 +3,7 @@ let node_process = require("node:process");
 node_process = require_chunk.__toESM(node_process, 1);
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.4.0-dev.1634+3b4bfbb6";
+var version = "2.4.0-dev.1655+b8f3c3d5";
 //#endregion
 //#region src/request.ts
 /**

package/dist/tests/request.test.cjs

@@ -1,5 +1,5 @@
 const require_chunk = require("./chunk-C2EiDwsr.cjs");
-const require_request = require("./request-Zpjq9m-W.cjs");
+const require_request = require("./request-DvEyU5Zf.cjs");
 let node_assert = require("node:assert");
 let node_test = require("node:test");
 let node_process = require("node:process");

package/dist/tests/request.test.mjs

@@ -1,4 +1,4 @@
-import { o as version, r as getUserAgent } from "./request-BWDludWb.mjs";
+import { o as version, r as getUserAgent } from "./request-B6s_F7bi.mjs";
 import { deepStrictEqual } from "node:assert";
 import { test } from "node:test";
 import process from "node:process";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.4.0-dev.1634+3b4bfbb6",
+  "version": "2.4.0-dev.1655+b8f3c3d5",
   "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",

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/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,