feat(node): crypto.randomUUID (#1697)

* feat(node): implement crypto.randomUUID()

Adds Node.js-compatible crypto.randomUUID() implementation that returns
RFC-4122 v4 UUID strings in lowercase format.

- Add randomUUID() to CryptoAPI interface
- Implement NodeCrypto module with ProxyExecutable exposure
- Add tests covering changes (5 tests) for format, uniqueness and options
- Uses java.util.UUID.randomUUID() for secure random generation

---------

Signed-off-by: Gordon MacMillan <[email protected]>

Author: GdMacmillan

packages/graalvm/api/graalvm.api

@@ -3679,6 +3679,8 @@ public abstract interface class elide/runtime/intrinsics/js/node/ConsoleAPI : el
 }
 
 public abstract interface class elide/runtime/intrinsics/js/node/CryptoAPI : elide/runtime/intrinsics/js/node/NodeAPI {
+	public abstract fun randomUUID (Lorg/graalvm/polyglot/Value;)Ljava/lang/String;
+	public static synthetic fun randomUUID$default (Lelide/runtime/intrinsics/js/node/CryptoAPI;Lorg/graalvm/polyglot/Value;ILjava/lang/Object;)Ljava/lang/String;
 }
 
 public abstract interface class elide/runtime/intrinsics/js/node/DNSAPI : elide/runtime/intrinsics/js/node/NodeAPI {

packages/graalvm/src/main/kotlin/elide/runtime/intrinsics/js/node/CryptoAPI.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024 Elide Technologies, Inc.
+ * Copyright (c) 2024-2025 Elide Technologies, Inc.
  *
  * Licensed under the MIT license (the "License"); you may not use this file except in compliance
  * with the License. You may obtain a copy of the License at
@@ -12,9 +12,22 @@
  */
 package elide.runtime.intrinsics.js.node
 
+import org.graalvm.polyglot.Value
 import elide.annotations.API
+import elide.vm.annotations.Polyglot
 
 /**
  * ## Node API: Crypto
  */
-@API public interface CryptoAPI : NodeAPI
+@API public interface CryptoAPI : NodeAPI {
+  /**
+   * ## Crypto: randomUUID
+   * Generates a random RFC 4122 version 4 UUID. The UUID is generated using a cryptographic pseudorandom number generator.
+   *
+   * See also: [Node Crypto API: `randomUUID`](https://nodejs.org/api/crypto.html#cryptorandomuuidoptions)
+   *
+   * @param options Optional settings (supports `disableEntropyCache` property, but is currently ignored)
+   * @return A randomly generated 36 character UUID c4 string in lowercase format (e.g. "5cb34cef-5fc2-47e4-a3ac-4bb055fa2025")
+   */
+  @Polyglot public fun randomUUID(options: Value? = null): String
+}

packages/graalvm/src/main/kotlin/elide/runtime/node/crypto/NodeCrypto.kt

@@ -12,6 +12,7 @@
  */
 package elide.runtime.node.crypto
 
+import org.graalvm.polyglot.Value
 import org.graalvm.polyglot.proxy.ProxyExecutable
 import elide.runtime.gvm.api.Intrinsic
 import elide.runtime.gvm.internals.intrinsics.js.AbstractNodeBuiltinModule
@@ -22,10 +23,14 @@ import elide.runtime.interop.ReadOnlyProxyObject
 import elide.runtime.intrinsics.GuestIntrinsic.MutableIntrinsicBindings
 import elide.runtime.intrinsics.js.node.CryptoAPI
 import elide.runtime.lang.javascript.NodeModuleName
+import elide.vm.annotations.Polyglot
 
 // Internal symbol where the Node built-in module is installed.
 private const val CRYPTO_MODULE_SYMBOL = "node_${NodeModuleName.CRYPTO}"
 
+// Functiopn name for randomUUID
+private const val F_RANDOM_UUID = "randomUUID"
+
 // Installs the Node crypto module into the intrinsic bindings.
 @Intrinsic internal class NodeCryptoModule : AbstractNodeBuiltinModule() {
   private val singleton by lazy { NodeCrypto.create() }
@@ -45,10 +50,32 @@ internal class NodeCrypto private constructor () : ReadOnlyProxyObject, CryptoAP
 
   internal companion object {
     @JvmStatic fun create(): NodeCrypto = NodeCrypto()
+
+    // Module members
+    private val moduleMembers = arrayOf(
+      F_RANDOM_UUID,
+    ).apply { sort() }
+  }
+
+  // Implement the CryptoAPI method
+  @Polyglot override fun randomUUID(options: Value?): String{
+    // Note `options` parameter exists for Node.js compatibility but is currently ignored
+    // It supports { disableEntropyCache: boolean } which is not applicable to our implementation
+    return java.util.UUID.randomUUID().toString()
   }
 
-  // @TODO not yet implemented
+  // ProxyObject implementation
+  override fun getMemberKeys(): Array<String> = moduleMembers
+
+  override fun hasMember(key: String): Boolean = 
+    moduleMembers.binarySearch(key) >= 0
 
-  override fun getMemberKeys(): Array<String> = emptyArray()
-  override fun getMember(key: String?): Any? = null
+  override fun getMember(key: String): Any? = when (key) {
+    F_RANDOM_UUID -> ProxyExecutable { args ->
+      // Node.js signature: randomUUID([options])
+      val options = args.getOrNull(0)
+      randomUUID(options)
+    }
+    else -> null
+  }
 }

packages/graalvm/src/test/kotlin/elide/runtime/node/NodeCryptoTest.kt

@@ -13,6 +13,10 @@
 package elide.runtime.node
 
 import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertIs
+import kotlin.test.assertNotEquals
+import kotlin.test.assertTrue
 import kotlin.test.assertNotNull
 import elide.annotations.Inject
 import elide.runtime.node.crypto.NodeCryptoModule
@@ -99,4 +103,99 @@ import elide.testing.annotations.TestCase
   @Test override fun testInjectable() {
     assertNotNull(crypto)
   }
+
+  @Test fun `randomUUID should return a string`() = conforms {
+    val uuid = crypto.provide().randomUUID(null)
+    assertIs<String>(uuid, "randomUUID should return a String")
+  }.guest {
+    //language=javascript
+    """
+    const crypto = require("crypto")
+    const assert = require("assert")
+
+    const uuid = crypto.randomUUID();
+    assert.equal(typeof uuid, "string");
+    """
+  }
+
+  @Test fun `randomUUID should return lowercase format`() = conforms {
+    val uuid = crypto.provide().randomUUID(null)
+    assertEquals(uuid, uuid.lowercase(), "UUID should be in lowercase format")
+  }.guest {
+    //language=javascript
+    """
+    const crypto = require("crypto")
+    const assert = require("assert")
+
+    const uuid = crypto.randomUUID();
+    assert.equal(uuid, uuid.toLowerCase(), "UUID should be lowercase");
+    """
+  }
+
+  @Test fun `randomUUID should return valid UUID v4 format`() = conforms {
+    val uuid = crypto.provide().randomUUID(null)
+
+    // UUID v4 format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+    // where y is one of [8,9,a,b]
+    val uuidRegex = Regex("^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$")
+    assertTrue(
+      uuidRegex.matches(uuid),
+      "UUID should match v4 format: $uuid"
+    )
+    assertEquals(36, uuid.length, "UUID should be 36 characters long")
+  }.guest {
+    //language=javascript
+    """
+    const crypto = require("crypto")
+    const assert = require("assert")
+
+    const uuid = crypto.randomUUID();
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+    assert.equal(uuid.length, 36, "UUID should be 36 characters");
+    assert.ok(uuidRegex.test(uuid), "UUID should match v4 format: " + uuid);
+    """
+  }
+
+  @Test fun `randomUUID should generate unique values`() = conforms {
+    val uuid1 = crypto.provide().randomUUID(null)
+    val uuid2 = crypto.provide().randomUUID(null)
+    val uuid3 = crypto.provide().randomUUID(null)
+
+    assertNotEquals(uuid1, uuid2, "UUIDS should be unique")
+    assertNotEquals(uuid2, uuid3, "UUIDS should be unique")
+    assertNotEquals(uuid1, uuid3, "UUIDS should be unique")
+  }.guest {
+    //language=javascript
+    """
+    const crypto = require("crypto")
+    const assert = require("assert")
+
+    const uuid1 = crypto.randomUUID();
+    const uuid2 = crypto.randomUUID();
+    const uuid3 = crypto.randomUUID();
+
+    assert.notEqual(uuid1, uuid2, "UUIDs should be unique");
+    assert.notEqual(uuid2, uuid3, "UUIDs should be unique");
+    assert.notEqual(uuid1, uuid3, "UUIDs should be unique");
+    """
+  }
+
+  @Test fun `randomUUID should accept optional options parameter`() = conforms {
+    // Options parameter is accepted but currently ignored
+    val uuid = crypto.provide().randomUUID(null)
+    assertNotNull(uuid)
+  }.guest {
+    //language=javascript
+    """
+    const crypto = require("crypto")
+    const assert = require("assert")
+
+    const uuid1 = crypto.randomUUID({ disableEntropyCache: true });
+    const uuid2 = crypto.randomUUID({ disableEntropyCache: false });
+
+    assert.equal(typeof uuid1, "string");
+    assert.equal(typeof uuid2, "string");
+    """
+  }
 }