feat(uuid): uuid v3 (#3324)

uuid/v3.ts

@@ -0,0 +1,61 @@
+// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+import { bytesToUuid, uuidToBytes } from "./_common.ts";
+import { concat } from "../bytes/concat.ts";
+import { assert } from "../_util/asserts.ts";
+import { crypto } from "../crypto/crypto.ts";
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[3][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+/**
+ * Validate that the passed UUID is an RFC4122 v3 UUID.
+ *
+ * @example
+ * ```ts
+ * import { generate as generateV3, validate } from "https://deno.land/std@$STD_VERSION/uuid/v3.ts";
+ *
+ * validate(await generateV3("6ba7b811-9dad-11d1-80b4-00c04fd430c8", new Uint8Array())); // true
+ * validate(crypto.randomUUID()); // false
+ * validate("this-is-not-a-uuid"); // false
+ * ```
+ */
+export function validate(id: string): boolean {
+  return UUID_RE.test(id);
+}
+
+/**
+ * Generate a RFC4122 v3 UUID (MD5 namespace).
+ *
+ * @example
+ * ```js
+ * import { generate } from "https://deno.land/std@$STD_VERSION/uuid/v3.ts";
+ *
+ * const NAMESPACE_URL = "6ba7b811-9dad-11d1-80b4-00c04fd430c8";
+ *
+ * const uuid = await generate(NAMESPACE_URL, new TextEncoder().encode("python.org"));
+ * uuid === "22fe6191-c161-3d86-a432-a81f343eda08" // true
+ * ```
+ *
+ * @param namespace The namespace to use, encoded as a UUID.
+ * @param data The data to hash to calculate the MD5 digest for the UUID.
+ */
+export async function generate(
+  namespace: string,
+  data: Uint8Array,
+): Promise<string> {
+  // TODO(lino-levan): validate that `namespace` is a valid UUID.
+
+  const space = uuidToBytes(namespace);
+  assert(space.length === 16, "namespace must be a valid UUID");
+
+  const toHash = concat(new Uint8Array(space), data);
+  const buffer = await crypto.subtle.digest("MD5", toHash);
+  const bytes = new Uint8Array(buffer);
+
+  bytes[6] = (bytes[6] & 0x0f) | 0x30;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+  return bytesToUuid(bytes);
+}

uuid/v3_test.ts

@@ -0,0 +1,39 @@
+// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
+import { assert, assertEquals } from "../testing/asserts.ts";
+import { generate, validate } from "./v3.ts";
+
+const NAMESPACE = "1b671a64-40d5-491e-99b0-da01ff1f3341";
+
+Deno.test("[UUID] test_uuid_v3", async () => {
+  const u = await generate(NAMESPACE, new Uint8Array());
+  assertEquals(typeof u, "string", "returns a string");
+  assert(u !== "", "return string is not empty");
+});
+
+Deno.test("[UUID] test_uuid_v3_format", async () => {
+  for (let i = 0; i < 10000; i++) {
+    const u = await generate(
+      NAMESPACE,
+      new TextEncoder().encode(i.toString()),
+    ) as string;
+    assert(validate(u), `${u} is not a valid uuid v5`);
+  }
+});
+
+Deno.test("[UUID] test_uuid_v3_option", async () => {
+  const u = await generate(NAMESPACE, new TextEncoder().encode("Hello, World"));
+  assertEquals(u, "71d7129f-e809-30ed-a2c6-ea9032b43c0d");
+});
+
+Deno.test("[UUID] is_valid_uuid_v3", async () => {
+  const u = await generate(
+    "1b671a64-40d5-491e-99b0-da01ff1f3341",
+    new TextEncoder().encode("Hello, World"),
+  );
+  const t = "4b4f2adc-5b27-37b5-8e3a-c4c4bcf94f05";
+  const n = "4b4f2adc-5b27-17b5-8e3a-c4c4bcf94f05";
+
+  assert(validate(u), `generated ${u} should be valid`);
+  assert(validate(t), `${t} should be valid`);
+  assert(!validate(n), `${n} should not be valid`);
+});

uuid/v5.ts

@@ -15,7 +15,7 @@ const UUID_RE =
  * ```ts
  * import { generate as generateV5, validate } from "https://deno.land/std@$STD_VERSION/uuid/v5.ts";
  *
- * validate(await generateV5("6ba7b810-9dad-11d1-80b4-00c04fd430c8", new Uint8Array())); // true
+ * validate(await generateV5("6ba7b811-9dad-11d1-80b4-00c04fd430c8", new Uint8Array())); // true
  * validate(crypto.randomUUID()); // false
  * validate("this-is-not-a-uuid"); // false
  * ```
@@ -31,10 +31,10 @@ export function validate(id: string): boolean {
  * ```js
  * import { generate } from "https://deno.land/std@$STD_VERSION/uuid/v5.ts";
  *
- * const NAMESPACE_URL = "6ba7b810-9dad-11d1-80b4-00c04fd430c8";
+ * const NAMESPACE_URL = "6ba7b811-9dad-11d1-80b4-00c04fd430c8";
  *
  * const uuid = await generate(NAMESPACE_URL, new TextEncoder().encode("python.org"));
- * uuid === "886313e1-3b8a-5372-9b90-0c9aee199e5d" // true
+ * uuid === "7af94e2b-4dd9-50f0-9c9a-8a48519bdef0" // true
  * ```
  *
  * @param namespace The namespace to use, encoded as a UUID.