@metamask-previews/cryptography 0.0.0-preview-d518059 → 0.0.0-preview-bba5d41

package/CHANGELOG.md

@@ -9,10 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Initial release ([#10282](https://github.com/MetaMask/core/pull/10282), [#10431](https://github.com/MetaMask/core/pull/10431), [#10403](https://github.com/MetaMask/core/pull/10403), [#10468](https://github.com/MetaMask/core/pull/10468))
+- Initial release ([#10282](https://github.com/MetaMask/core/pull/10282), [#10431](https://github.com/MetaMask/core/pull/10431), [#10403](https://github.com/MetaMask/core/pull/10403), [#10468](https://github.com/MetaMask/core/pull/10468), [#10503](https://github.com/MetaMask/core/pull/10503), [#10563](https://github.com/MetaMask/core/pull/10563))
   - Add `sha256`, `sha384`, and `sha512` functions for computing SHA digests
   - Add `hmacSha256`, `hmacSha384`, and `hmacSha512` functions for computing HMAC digests
   - Add `pbkdf2Sha256`, `pbkdf2Sha384`, and `pbkdf2Sha512` functions for key derivation
   - Add `hkdfSha256`, `hkdfSha384`, and `hkdfSha512` functions for key derivation
+  - Add `getPublicKey` and `getSharedSecret` functions for X25519 key derivation exported via `@metamask/cryptography/x25519`
+  - Add `getRandomBytes` function for generating cryptographically secure random bytes
 
 [Unreleased]: https://github.com/MetaMask/core/

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './hkdf.js';
 export * from './hmac.js';
 export * from './pbkdf2.js';
+export * from './random.js';
 export * from './sha.js';
 export type * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,mBAAmB,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,mBAAmB,YAAY,CAAC"}

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from './hkdf.js';
 export * from './hmac.js';
 export * from './pbkdf2.js';
+export * from './random.js';
 export * from './sha.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC","sourcesContent":["export * from './hkdf.js';\nexport * from './hmac.js';\nexport * from './pbkdf2.js';\nexport * from './sha.js';\nexport type * from './types.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC","sourcesContent":["export * from './hkdf.js';\nexport * from './hmac.js';\nexport * from './pbkdf2.js';\nexport * from './random.js';\nexport * from './sha.js';\nexport type * from './types.js';\n"]}

package/dist/random.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generate random bytes using the platform's cryptographically secure pseudo-random number generator (CSPRNG).
+ *
+ * @param length - The number of random bytes to generate.
+ * @returns An `Uint8Array` of the provided length with random bytes.
+ * @throws If `length` is not greater than 0.
+ */
+export declare function getRandomBytes(length: number): Uint8Array;
+//# sourceMappingURL=random.d.ts.map

package/dist/random.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.d.ts","sourceRoot":"","sources":["../src/random.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAKzD"}

package/dist/random.js

@@ -0,0 +1,14 @@
+/**
+ * Generate random bytes using the platform's cryptographically secure pseudo-random number generator (CSPRNG).
+ *
+ * @param length - The number of random bytes to generate.
+ * @returns An `Uint8Array` of the provided length with random bytes.
+ * @throws If `length` is not greater than 0.
+ */
+export function getRandomBytes(length) {
+    if (length <= 0) {
+        throw new Error('Invalid length: Length must be greater than 0.');
+    }
+    return globalThis.crypto.getRandomValues(new Uint8Array(length));
+}
+//# sourceMappingURL=random.js.map

package/dist/random.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.js","sourceRoot":"","sources":["../src/random.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,UAAU,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AACnE,CAAC","sourcesContent":["/**\n * Generate random bytes using the platform's cryptographically secure pseudo-random number generator (CSPRNG).\n *\n * @param length - The number of random bytes to generate.\n * @returns An `Uint8Array` of the provided length with random bytes.\n * @throws If `length` is not greater than 0.\n */\nexport function getRandomBytes(length: number): Uint8Array {\n  if (length <= 0) {\n    throw new Error('Invalid length: Length must be greater than 0.');\n  }\n  return globalThis.crypto.getRandomValues(new Uint8Array(length));\n}\n"]}

package/dist/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Convert a `BufferSource` to a `Uint8Array` view over the same bytes.
+ *
+ * @param source - The `ArrayBuffer`, typed array, or `DataView` to convert.
+ * @returns A `Uint8Array` sharing memory with the source.
+ */
+export declare function toUint8Array(source: BufferSource): Uint8Array;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,CAK7D"}

package/dist/utils.js

@@ -0,0 +1,13 @@
+/**
+ * Convert a `BufferSource` to a `Uint8Array` view over the same bytes.
+ *
+ * @param source - The `ArrayBuffer`, typed array, or `DataView` to convert.
+ * @returns A `Uint8Array` sharing memory with the source.
+ */
+export function toUint8Array(source) {
+    if (source instanceof ArrayBuffer) {
+        return new Uint8Array(source);
+    }
+    return new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,IAAI,MAAM,YAAY,WAAW,EAAE,CAAC;QAClC,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;AAC7E,CAAC","sourcesContent":["/**\n * Convert a `BufferSource` to a `Uint8Array` view over the same bytes.\n *\n * @param source - The `ArrayBuffer`, typed array, or `DataView` to convert.\n * @returns A `Uint8Array` sharing memory with the source.\n */\nexport function toUint8Array(source: BufferSource): Uint8Array {\n  if (source instanceof ArrayBuffer) {\n    return new Uint8Array(source);\n  }\n  return new Uint8Array(source.buffer, source.byteOffset, source.byteLength);\n}\n"]}

package/dist/x25519.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Derive the X25519 public key corresponding to a private key.
+ *
+ * @param privateKey - The 32-byte X25519 private key.
+ * @returns The 32-byte X25519 public key.
+ */
+export declare function getPublicKey(privateKey: BufferSource): Promise<Uint8Array>;
+/**
+ * Compute the X25519 shared secret given a private key and a peer's public key.
+ *
+ * @param privateKey - The 32-byte X25519 private key.
+ * @param publicKey - The 32-byte X25519 public key of the peer.
+ * @returns The 32-byte shared secret.
+ */
+export declare function getSharedSecret(privateKey: BufferSource, publicKey: BufferSource): Promise<Uint8Array>;
+//# sourceMappingURL=x25519.d.ts.map

package/dist/x25519.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x25519.d.ts","sourceRoot":"","sources":["../src/x25519.ts"],"names":[],"mappings":"AAqEA;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,YAAY,GACvB,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,YAAY,EACxB,SAAS,EAAE,YAAY,GACtB,OAAO,CAAC,UAAU,CAAC,CAGrB"}

package/dist/x25519.js

@@ -0,0 +1,57 @@
+import { toUint8Array } from './utils.js';
+const X25519_KEY_LENGTH = 32;
+// https://www.rfc-editor.org/rfc/rfc7748#section-4.1
+const X25519_BASE_POINT = new Uint8Array(32);
+X25519_BASE_POINT[0] = 9;
+// https://www.rfc-editor.org/rfc/rfc8410#section-7
+// https://github.com/nodejs/node/blob/main/test/parallel/test-webcrypto-export-import-cfrg.js
+const X25519_PKCS8_HEADER = new Uint8Array([
+    0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04,
+    0x22, 0x04, 0x20,
+]);
+/**
+ * Perform scalar multiplication of a point by a private key,
+ * specified as the X25519 function in RFC 7748, Section 5.
+ *
+ * @param privateKey - The 32-byte X25519 private key (scalar).
+ * @param publicKey - The 32-byte X25519 public key (u-coordinate).
+ * @returns The 32-byte result of the scalar multiplication.
+ */
+async function scalarMultiply(privateKey, publicKey) {
+    if (privateKey.byteLength !== X25519_KEY_LENGTH) {
+        throw new Error(`Invalid private key length: Private key must be exactly ${X25519_KEY_LENGTH} bytes for X25519.`);
+    }
+    if (publicKey.byteLength !== X25519_KEY_LENGTH) {
+        throw new Error(`Invalid public key length: Public key must be exactly ${X25519_KEY_LENGTH} bytes for X25519.`);
+    }
+    // The WebCrypto API expects private keys to be in PKCS8 format.
+    const pkcs8 = new Uint8Array(X25519_PKCS8_HEADER.length + X25519_KEY_LENGTH);
+    pkcs8.set(X25519_PKCS8_HEADER);
+    pkcs8.set(toUint8Array(privateKey), X25519_PKCS8_HEADER.length);
+    const subtlePrivateKey = await globalThis.crypto.subtle.importKey('pkcs8', pkcs8, { name: 'X25519' }, false, ['deriveBits']);
+    const subtlePublicKey = await globalThis.crypto.subtle.importKey('raw', publicKey, { name: 'X25519' }, false, []);
+    const result = await globalThis.crypto.subtle.deriveBits({ name: 'X25519', public: subtlePublicKey }, subtlePrivateKey, X25519_KEY_LENGTH * 8);
+    return new Uint8Array(result);
+}
+/**
+ * Derive the X25519 public key corresponding to a private key.
+ *
+ * @param privateKey - The 32-byte X25519 private key.
+ * @returns The 32-byte X25519 public key.
+ */
+export async function getPublicKey(privateKey) {
+    // X25519 public keys are derived as X25519(k, 9)
+    return scalarMultiply(privateKey, X25519_BASE_POINT);
+}
+/**
+ * Compute the X25519 shared secret given a private key and a peer's public key.
+ *
+ * @param privateKey - The 32-byte X25519 private key.
+ * @param publicKey - The 32-byte X25519 public key of the peer.
+ * @returns The 32-byte shared secret.
+ */
+export async function getSharedSecret(privateKey, publicKey) {
+    // X25519 shared secrets are derived as X25519(a, K_b)
+    return scalarMultiply(privateKey, publicKey);
+}
+//# sourceMappingURL=x25519.js.map

package/dist/x25519.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x25519.js","sourceRoot":"","sources":["../src/x25519.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B,qDAAqD;AACrD,MAAM,iBAAiB,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;AAC7C,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAEzB,mDAAmD;AACnD,8FAA8F;AAC9F,MAAM,mBAAmB,GAAG,IAAI,UAAU,CAAC;IACzC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;IAC5E,IAAI,EAAE,IAAI,EAAE,IAAI;CACjB,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,KAAK,UAAU,cAAc,CAC3B,UAAwB,EACxB,SAAuB;IAEvB,IAAI,UAAU,CAAC,UAAU,KAAK,iBAAiB,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CACb,2DAA2D,iBAAiB,oBAAoB,CACjG,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,CAAC,UAAU,KAAK,iBAAiB,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CACb,yDAAyD,iBAAiB,oBAAoB,CAC/F,CAAC;IACJ,CAAC;IAED,gEAAgE;IAChE,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,mBAAmB,CAAC,MAAM,GAAG,iBAAiB,CAAC,CAAC;IAC7E,KAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAC/B,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAEhE,MAAM,gBAAgB,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAC/D,OAAO,EACP,KAAK,EACL,EAAE,IAAI,EAAE,QAAQ,EAAE,EAClB,KAAK,EACL,CAAC,YAAY,CAAC,CACf,CAAC;IAEF,MAAM,eAAe,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAC9D,KAAK,EACL,SAAS,EACT,EAAE,IAAI,EAAE,QAAQ,EAAE,EAClB,KAAK,EACL,EAAE,CACH,CAAC;IAEF,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CACtD,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,EAC3C,gBAAgB,EAChB,iBAAiB,GAAG,CAAC,CACtB,CAAC;IAEF,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,UAAwB;IAExB,iDAAiD;IACjD,OAAO,cAAc,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,UAAwB,EACxB,SAAuB;IAEvB,sDAAsD;IACtD,OAAO,cAAc,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AAC/C,CAAC","sourcesContent":["import { toUint8Array } from './utils.js';\n\nconst X25519_KEY_LENGTH = 32;\n\n// https://www.rfc-editor.org/rfc/rfc7748#section-4.1\nconst X25519_BASE_POINT = new Uint8Array(32);\nX25519_BASE_POINT[0] = 9;\n\n// https://www.rfc-editor.org/rfc/rfc8410#section-7\n// https://github.com/nodejs/node/blob/main/test/parallel/test-webcrypto-export-import-cfrg.js\nconst X25519_PKCS8_HEADER = new Uint8Array([\n  0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04,\n  0x22, 0x04, 0x20,\n]);\n\n/**\n * Perform scalar multiplication of a point by a private key,\n * specified as the X25519 function in RFC 7748, Section 5.\n *\n * @param privateKey - The 32-byte X25519 private key (scalar).\n * @param publicKey - The 32-byte X25519 public key (u-coordinate).\n * @returns The 32-byte result of the scalar multiplication.\n */\nasync function scalarMultiply(\n  privateKey: BufferSource,\n  publicKey: BufferSource,\n): Promise<Uint8Array> {\n  if (privateKey.byteLength !== X25519_KEY_LENGTH) {\n    throw new Error(\n      `Invalid private key length: Private key must be exactly ${X25519_KEY_LENGTH} bytes for X25519.`,\n    );\n  }\n\n  if (publicKey.byteLength !== X25519_KEY_LENGTH) {\n    throw new Error(\n      `Invalid public key length: Public key must be exactly ${X25519_KEY_LENGTH} bytes for X25519.`,\n    );\n  }\n\n  // The WebCrypto API expects private keys to be in PKCS8 format.\n  const pkcs8 = new Uint8Array(X25519_PKCS8_HEADER.length + X25519_KEY_LENGTH);\n  pkcs8.set(X25519_PKCS8_HEADER);\n  pkcs8.set(toUint8Array(privateKey), X25519_PKCS8_HEADER.length);\n\n  const subtlePrivateKey = await globalThis.crypto.subtle.importKey(\n    'pkcs8',\n    pkcs8,\n    { name: 'X25519' },\n    false,\n    ['deriveBits'],\n  );\n\n  const subtlePublicKey = await globalThis.crypto.subtle.importKey(\n    'raw',\n    publicKey,\n    { name: 'X25519' },\n    false,\n    [],\n  );\n\n  const result = await globalThis.crypto.subtle.deriveBits(\n    { name: 'X25519', public: subtlePublicKey },\n    subtlePrivateKey,\n    X25519_KEY_LENGTH * 8,\n  );\n\n  return new Uint8Array(result);\n}\n\n/**\n * Derive the X25519 public key corresponding to a private key.\n *\n * @param privateKey - The 32-byte X25519 private key.\n * @returns The 32-byte X25519 public key.\n */\nexport async function getPublicKey(\n  privateKey: BufferSource,\n): Promise<Uint8Array> {\n  // X25519 public keys are derived as X25519(k, 9)\n  return scalarMultiply(privateKey, X25519_BASE_POINT);\n}\n\n/**\n * Compute the X25519 shared secret given a private key and a peer's public key.\n *\n * @param privateKey - The 32-byte X25519 private key.\n * @param publicKey - The 32-byte X25519 public key of the peer.\n * @returns The 32-byte shared secret.\n */\nexport async function getSharedSecret(\n  privateKey: BufferSource,\n  publicKey: BufferSource,\n): Promise<Uint8Array> {\n  // X25519 shared secrets are derived as X25519(a, K_b)\n  return scalarMultiply(privateKey, publicKey);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamask-previews/cryptography",
-  "version": "0.0.0-preview-d518059",
+  "version": "0.0.0-preview-bba5d41",
   "description": "Provides optimized versions of commonly used cryptography functions for MetaMask clients",
   "keywords": [
     "Ethereum",
@@ -25,6 +25,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./x25519": {
+      "types": "./dist/x25519.d.ts",
+      "default": "./dist/x25519.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -39,8 +43,8 @@
     "build:only-clean": "rimraf './dist' './tsconfig.build.tsbuildinfo'",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/cryptography",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/cryptography",
-    "lint:tsconfigs": "tsx ../../scripts/lint-tsconfigs/lint-tsconfigs.mts",
-    "lint:tsconfigs:fix": "tsx ../../scripts/lint-tsconfigs/lint-tsconfigs.mts --fix",
+    "lint:tsconfigs": "tsx ../../scripts/lint-tsconfigs/lint-tsconfigs.ts",
+    "lint:tsconfigs:fix": "tsx ../../scripts/lint-tsconfigs/lint-tsconfigs.ts --fix",
     "messenger-action-types:check": "tsx ../../packages/messenger-cli/src/cli.ts --formatter oxfmt --check",
     "messenger-action-types:generate": "tsx ../../packages/messenger-cli/src/cli.ts --formatter oxfmt --generate",
     "since-latest-release": "../../scripts/since-latest-release.sh",
@@ -55,7 +59,7 @@
     "@types/jest": "^30.0.0",
     "@typescript/native": "npm:typescript@^7.0.2",
     "deepmerge": "^4.3.1",
-    "jest": "^30.4.2",
+    "jest": "^30.5.2",
     "rimraf": "^6.1.3",
     "ts-jest": "^29.4.14",
     "tsx": "^4.23.15",