@reclaimprotocol/attestor-core 5.0.1-beta.2 → 5.0.1-beta.22

package/lib/utils/generics.js

@@ -1,268 +1,317 @@
-import {
-  areUint8ArraysEqual,
-  CONTENT_TYPE_MAP,
-  crypto,
-  decryptWrappedRecord,
-  PACKET_TYPE,
-  SUPPORTED_CIPHER_SUITE_MAP,
-  uint8ArrayToBinaryStr,
-  uint8ArrayToDataView
-} from "@reclaimprotocol/tls";
-import { REDACTION_CHAR_CODE } from "@reclaimprotocol/zk-symmetric-crypto";
+import { areUint8ArraysEqual, CONTENT_TYPE_MAP, crypto, decryptWrappedRecord, PACKET_TYPE, SUPPORTED_CIPHER_SUITE_MAP, uint8ArrayToBinaryStr, uint8ArrayToDataView } from '@reclaimprotocol/tls';
+import { REDACTION_CHAR_CODE } from '@reclaimprotocol/zk-symmetric-crypto';
 import { RPCMessage, RPCMessages } from "../proto/api.js";
-const DEFAULT_REDACTION_DATA = new Uint8Array(4).fill(REDACTION_CHAR_CODE);
-function uint8ArrayToStr(arr) {
-  return new TextDecoder().decode(arr);
+const DEFAULT_REDACTION_DATA = new Uint8Array(4)
+    .fill(REDACTION_CHAR_CODE);
+export { uint8ArrayToBinaryStr };
+/**
+ * Decodes a Uint8Array to a UTF-8 string.
+ */
+export function uint8ArrayToStr(arr) {
+    return new TextDecoder().decode(arr);
 }
-function strToUint8Array(str) {
-  return new TextEncoder().encode(str);
+/**
+ * Encodes a UTF-8 string to a Uint8Array.
+ */
+export function strToUint8Array(str) {
+    return new TextEncoder().encode(str);
 }
-function getTranscriptString(receipt) {
-  const applMsgs = extractApplicationDataFromTranscript(receipt);
-  const strList = [];
-  for (const { message, sender } of applMsgs) {
-    const content = uint8ArrayToStr(message);
-    if (strList[strList.length - 1]?.startsWith(sender)) {
-      strList[strList.length - 1] += content;
-    } else {
-      strList.push(`${sender}: ${content}`);
+export function getTranscriptString(receipt) {
+    const applMsgs = extractApplicationDataFromTranscript(receipt);
+    const strList = [];
+    for (const { message, sender } of applMsgs) {
+        const content = uint8ArrayToStr(message);
+        if (strList[strList.length - 1]?.startsWith(sender)) {
+            strList[strList.length - 1] += content;
+        }
+        else {
+            strList.push(`${sender}: ${content}`);
+        }
     }
-  }
-  return strList.join("\n");
+    return strList.join('\n');
 }
-const unixTimestampSeconds = () => Math.floor(Date.now() / 1e3);
-function findIndexInUint8Array(haystack, needle) {
-  for (let i = 0; i < haystack.length; i++) {
-    if (areUint8ArraysEqual(haystack.slice(i, i + needle.length), needle)) {
-      return i;
+export const unixTimestampSeconds = () => Math.floor(Date.now() / 1000);
+/**
+ * Find index of needle in haystack
+ */
+export function findIndexInUint8Array(haystack, needle) {
+    for (let i = 0; i < haystack.length; i++) {
+        if (areUint8ArraysEqual(haystack.slice(i, i + needle.length), needle)) {
+            return i;
+        }
     }
-  }
-  return -1;
-}
-function getZkAlgorithmForCipherSuite(cipherSuite) {
-  if (cipherSuite.includes("CHACHA20")) {
-    return "chacha20";
-  }
-  if (cipherSuite.includes("AES_256_GCM")) {
-    return "aes-256-ctr";
-  }
-  if (cipherSuite.includes("AES_128_GCM")) {
-    return "aes-128-ctr";
-  }
-  throw new Error(`${cipherSuite} not supported for ZK ops`);
+    return -1;
 }
-function getPureCiphertext(content, cipherSuite) {
-  getZkAlgorithmForCipherSuite(cipherSuite);
-  content = content.slice(0, -16);
-  const {
-    ivLength: fixedIvLength
-  } = SUPPORTED_CIPHER_SUITE_MAP[cipherSuite];
-  const recordIvLength = 12 - fixedIvLength;
-  content = content.slice(recordIvLength);
-  return content;
+/**
+ * Fetch the ZK algorithm for the specified cipher suite
+ */
+export function getZkAlgorithmForCipherSuite(cipherSuite) {
+    if (cipherSuite.includes('CHACHA20')) {
+        return 'chacha20';
+    }
+    if (cipherSuite.includes('AES_256_GCM')) {
+        return 'aes-256-ctr';
+    }
+    if (cipherSuite.includes('AES_128_GCM')) {
+        return 'aes-128-ctr';
+    }
+    throw new Error(`${cipherSuite} not supported for ZK ops`);
 }
-function getRecordIV(content, cipherSuite) {
-  getZkAlgorithmForCipherSuite(cipherSuite);
-  const {
-    ivLength: fixedIvLength
-  } = SUPPORTED_CIPHER_SUITE_MAP[cipherSuite];
-  const recordIvLength = 12 - fixedIvLength;
-  return content.slice(0, recordIvLength);
+/**
+ * Get the pure ciphertext without any MAC,
+ * or authentication tag,
+ * @param content content w/o header
+ * @param cipherSuite
+ */
+export function getPureCiphertext(content, cipherSuite) {
+    // assert that the cipher suite is supported
+    getZkAlgorithmForCipherSuite(cipherSuite);
+    // 16 => auth tag length
+    content = content.slice(0, -16);
+    const { ivLength: fixedIvLength, } = SUPPORTED_CIPHER_SUITE_MAP[cipherSuite];
+    // 12 => total IV length
+    const recordIvLength = 12 - fixedIvLength;
+    // record IV is prefixed to the ciphertext
+    content = content.slice(recordIvLength);
+    return content;
 }
-function getProviderValue(params, fn, secretParams) {
-  return typeof fn === "function" ? fn(params, secretParams) : fn;
+/**
+ * Get the 8 byte IV part that's stored in the record for some cipher suites
+ * @param content content w/o header
+ * @param cipherSuite
+ */
+export function getRecordIV(content, cipherSuite) {
+    // assert that the cipher suite is supported
+    getZkAlgorithmForCipherSuite(cipherSuite);
+    const { ivLength: fixedIvLength, } = SUPPORTED_CIPHER_SUITE_MAP[cipherSuite];
+    // 12 => total IV length
+    const recordIvLength = 12 - fixedIvLength;
+    return content.slice(0, recordIvLength);
 }
-function generateRpcMessageId() {
-  return uint8ArrayToDataView(crypto.randomBytes(4)).getUint32(0);
+export function getProviderValue(params, fn, secretParams) {
+    return typeof fn === 'function'
+        // @ts-ignore
+        ? fn(params, secretParams)
+        : fn;
 }
-function generateSessionId() {
-  return generateRpcMessageId();
+export function generateRpcMessageId() {
+    return uint8ArrayToDataView(crypto.randomBytes(4)).getUint32(0);
 }
-function generateTunnelId() {
-  return generateRpcMessageId();
+/**
+ * Random session ID for a WebSocket client.
+ */
+export function generateSessionId() {
+    return generateRpcMessageId();
 }
-function makeRpcEvent(type, data) {
-  const ev = new Event(type);
-  ev.data = data;
-  return ev;
+/**
+ * Random ID for a tunnel.
+ */
+export function generateTunnelId() {
+    return generateRpcMessageId();
 }
-function getRpcTypeFromKey(key) {
-  if (key.endsWith("Request")) {
-    return {
-      type: key.slice(0, -7),
-      direction: "request"
-    };
-  }
-  if (key.endsWith("Response")) {
-    return {
-      type: key.slice(0, -8),
-      direction: "response"
-    };
-  }
+export function makeRpcEvent(type, data) {
+    const ev = new Event(type);
+    ev.data = data;
+    return ev;
 }
-function getRpcResponseType(type) {
-  return `${type}Response`;
+/**
+ * Get the RPC type from the key.
+ * For eg. "claimTunnelRequest" ->
+ *    { type: 'claimTunnel', direction: 'request' }
+ */
+export function getRpcTypeFromKey(key) {
+    if (key.endsWith('Request')) {
+        return {
+            type: key.slice(0, -7),
+            direction: 'request'
+        };
+    }
+    if (key.endsWith('Response')) {
+        return {
+            type: key.slice(0, -8),
+            direction: 'response'
+        };
+    }
 }
-function getRpcRequestType(type) {
-  return `${type}Request`;
+/**
+ * Get the RPC response type from the RPC type.
+ * For eg. "claimTunnel" -> "claimTunnelResponse"
+ */
+export function getRpcResponseType(type) {
+    return `${type}Response`;
 }
-function isApplicationData(packet, tlsVersion) {
-  return packet.type === "ciphertext" && (packet.contentType === "APPLICATION_DATA" || packet.data[0] === PACKET_TYPE.WRAPPED_RECORD && tlsVersion === "TLS1_2");
+/**
+ * Get the RPC request type from the RPC type.
+ * For eg. "claimTunnel" -> "claimTunnelRequest"
+ */
+export function getRpcRequestType(type) {
+    return `${type}Request`;
 }
-async function extractArrayBufferFromWsData(data) {
-  if (data instanceof ArrayBuffer) {
-    return new Uint8Array(data);
-  }
-  if (data instanceof Uint8Array || typeof data === "object" && data && "buffer" in data) {
-    return data;
-  }
-  if (typeof data === "string") {
-    return strToUint8Array(data);
-  }
-  if (typeof Blob !== "undefined" && data instanceof Blob) {
-    return new Uint8Array(await data.arrayBuffer());
-  }
-  throw new Error("unsupported data: " + String(data));
+export function isApplicationData(packet, tlsVersion) {
+    return packet.type === 'ciphertext'
+        && (packet.contentType === 'APPLICATION_DATA'
+            || (packet.data[0] === PACKET_TYPE.WRAPPED_RECORD
+                && tlsVersion === 'TLS1_2'));
 }
-function getRpcRequest(msg) {
-  if (msg.requestError) {
-    return {
-      direction: "response",
-      type: "error"
-    };
-  }
-  for (const key in msg) {
-    if (!msg[key]) {
-      continue;
+/**
+ * Convert the received data from a WS to a Uint8Array
+ */
+export async function extractArrayBufferFromWsData(data) {
+    if (data instanceof ArrayBuffer) {
+        return new Uint8Array(data);
     }
-    const rpcType = getRpcTypeFromKey(key);
-    if (!rpcType) {
-      continue;
+    // uint8array/Buffer
+    if (data instanceof Uint8Array
+        || (typeof data === 'object' && data && 'buffer' in data)) {
+        return data;
     }
-    return rpcType;
-  }
-}
-function extractApplicationDataFromTranscript({ transcript, tlsVersion }) {
-  const msgs = [];
-  for (const m of transcript) {
-    let message;
-    if (m.redacted) {
-      if (!m.plaintextLength) {
-        message = DEFAULT_REDACTION_DATA;
-      } else {
-        const len = tlsVersion === "TLS1_3" ? m.plaintextLength - 1 : m.plaintextLength;
-        message = new Uint8Array(len).fill(REDACTION_CHAR_CODE);
-      }
-    } else if (tlsVersion === "TLS1_3") {
-      const contentType = m.message[m.message.length - 1];
-      if (contentType !== CONTENT_TYPE_MAP["APPLICATION_DATA"]) {
-        continue;
-      }
-      message = m.message.slice(0, -1);
-    } else if (m.recordHeader[0] === PACKET_TYPE.WRAPPED_RECORD) {
-      message = m.message;
-    } else {
-      continue;
+    if (typeof data === 'string') {
+        return strToUint8Array(data);
     }
-    msgs.push({ message, sender: m.sender });
-  }
-  return msgs;
+    if (typeof Blob !== 'undefined' && data instanceof Blob) {
+        return new Uint8Array(await data.arrayBuffer());
+    }
+    throw new Error('unsupported data: ' + String(data));
 }
-function extractHandshakeFromTranscript({ transcript, tlsVersion }) {
-  const msgs = [];
-  for (const [i, m] of transcript.entries()) {
-    if (m.redacted) {
-      break;
+/**
+ * Check if the RPC message is a request or a response.
+ */
+export function getRpcRequest(msg) {
+    if (msg.requestError) {
+        return {
+            direction: 'response',
+            type: 'error'
+        };
     }
-    let message;
-    if (m.recordHeader[0] === PACKET_TYPE.HELLO) {
-      message = m.message;
-    } else if (m.recordHeader[0] === PACKET_TYPE.WRAPPED_RECORD) {
-      if (tlsVersion === "TLS1_3") {
-        const contentType = m.message[m.message.length - 1];
-        if (contentType !== CONTENT_TYPE_MAP["HANDSHAKE"]) {
-          break;
+    for (const key in msg) {
+        if (!msg[key]) {
+            continue;
+        }
+        const rpcType = getRpcTypeFromKey(key);
+        if (!rpcType) {
+            continue;
         }
-        message = m.message.slice(0, -1);
-      } else {
-        break;
-      }
-    } else {
-      continue;
+        return rpcType;
     }
-    if (!message.length) {
-      throw new Error("unsupported handshake message");
+}
+/**
+ * Finds all application data messages in a transcript
+ * and returns them. Removes the "contentType" suffix from the message.
+ * in TLS 1.3
+ */
+export function extractApplicationDataFromTranscript({ transcript, tlsVersion }) {
+    const msgs = [];
+    for (const m of transcript) {
+        let message;
+        // redacted msgs but with a valid packet header
+        // can be considered application data messages
+        if (m.redacted) {
+            if (!m.plaintextLength) {
+                message = DEFAULT_REDACTION_DATA;
+            }
+            else {
+                const len = tlsVersion === 'TLS1_3'
+                    // remove content type suffix
+                    ? m.plaintextLength - 1
+                    : m.plaintextLength;
+                message = new Uint8Array(len)
+                    .fill(REDACTION_CHAR_CODE);
+            }
+            // otherwise, we need to check the content type
+        }
+        else if (tlsVersion === 'TLS1_3') {
+            const contentType = m.message[m.message.length - 1];
+            if (contentType !== CONTENT_TYPE_MAP['APPLICATION_DATA']) {
+                continue;
+            }
+            message = m.message.slice(0, -1);
+        }
+        else if (m.recordHeader[0] === PACKET_TYPE.WRAPPED_RECORD) {
+            message = m.message;
+        }
+        else {
+            continue;
+        }
+        msgs.push({ message, sender: m.sender });
     }
-    msgs.push({ message, sender: m.sender, index: i });
-  }
-  return msgs;
+    return msgs;
 }
-async function decryptDirect(directReveal, cipherSuite, recordHeader, serverTlsVersion, content) {
-  const { key, iv, recordNumber } = directReveal;
-  const { cipher } = SUPPORTED_CIPHER_SUITE_MAP[cipherSuite];
-  const importedKey = await crypto.importKey(cipher, key);
-  return await decryptWrappedRecord(
-    content,
-    {
-      iv,
-      key: importedKey,
-      recordHeader,
-      recordNumber,
-      version: serverTlsVersion,
-      cipherSuite
+export function extractHandshakeFromTranscript({ transcript, tlsVersion }) {
+    const msgs = [];
+    for (const [i, m] of transcript.entries()) {
+        if (m.redacted) {
+            break; // stop at first encrypted message
+        }
+        let message;
+        if (m.recordHeader[0] === PACKET_TYPE.HELLO) {
+            message = m.message;
+        }
+        else if (m.recordHeader[0] === PACKET_TYPE.WRAPPED_RECORD) {
+            if (tlsVersion === 'TLS1_3') {
+                const contentType = m.message[m.message.length - 1];
+                if (contentType !== CONTENT_TYPE_MAP['HANDSHAKE']) {
+                    break;
+                }
+                message = m.message.slice(0, -1);
+            }
+            else {
+                break;
+            }
+        }
+        else {
+            continue;
+        }
+        if (!message.length) {
+            throw new Error('unsupported handshake message');
+        }
+        msgs.push({ message, sender: m.sender, index: i });
     }
-  );
+    return msgs;
+}
+export async function decryptDirect(directReveal, cipherSuite, recordHeader, serverTlsVersion, content) {
+    const { key, iv, recordNumber } = directReveal;
+    const { cipher } = SUPPORTED_CIPHER_SUITE_MAP[cipherSuite];
+    const importedKey = await crypto.importKey(cipher, key);
+    return await decryptWrappedRecord(content, {
+        iv,
+        key: importedKey,
+        recordHeader,
+        recordNumber,
+        version: serverTlsVersion,
+        cipherSuite,
+    });
 }
-function packRpcMessages(...msgs) {
-  return RPCMessages.create({
-    messages: msgs.map((msg) => RPCMessage.create({
-      ...msg,
-      id: msg.id || generateRpcMessageId()
-    }))
-  });
+export function packRpcMessages(...msgs) {
+    return RPCMessages.create({
+        messages: msgs.map(msg => (RPCMessage.create({
+            ...msg,
+            id: msg.id || generateRpcMessageId()
+        })))
+    });
 }
-function ethersStructToPlainObject(struct) {
-  if (!Array.isArray(struct)) {
-    return struct;
-  }
-  const namedKeys = Object.keys(struct).filter((key) => isNaN(Number(key)));
-  if (!namedKeys.length) {
-    return struct.map(ethersStructToPlainObject);
-  }
-  const obj = {};
-  for (const key of namedKeys) {
-    obj[key] = ethersStructToPlainObject(struct[key]);
-  }
-  return obj;
+/**
+ * Converts an Ethers struct (an array w named keys) to
+ * a plain object. Recursively converts all structs inside.
+ * Required to correctly JSON.stringify the struct.
+ */
+export function ethersStructToPlainObject(struct) {
+    if (!Array.isArray(struct)) {
+        return struct;
+    }
+    const namedKeys = Object.keys(struct)
+        .filter(key => isNaN(Number(key)));
+    // seems to be an actual array
+    if (!namedKeys.length) {
+        return struct.map(ethersStructToPlainObject);
+    }
+    const obj = {};
+    for (const key of namedKeys) {
+        obj[key] = ethersStructToPlainObject(struct[key]);
+    }
+    return obj;
 }
-function isTls13Suite(suite) {
-  return suite === "TLS_AES_128_GCM_SHA256" || suite === "TLS_AES_256_GCM_SHA384" || suite === "TLS_CHACHA20_POLY1305_SHA256";
+export function isTls13Suite(suite) {
+    return suite === 'TLS_AES_128_GCM_SHA256'
+        || suite === 'TLS_AES_256_GCM_SHA384'
+        || suite === 'TLS_CHACHA20_POLY1305_SHA256';
 }
-export {
-  decryptDirect,
-  ethersStructToPlainObject,
-  extractApplicationDataFromTranscript,
-  extractArrayBufferFromWsData,
-  extractHandshakeFromTranscript,
-  findIndexInUint8Array,
-  generateRpcMessageId,
-  generateSessionId,
-  generateTunnelId,
-  getProviderValue,
-  getPureCiphertext,
-  getRecordIV,
-  getRpcRequest,
-  getRpcRequestType,
-  getRpcResponseType,
-  getRpcTypeFromKey,
-  getTranscriptString,
-  getZkAlgorithmForCipherSuite,
-  isApplicationData,
-  isTls13Suite,
-  makeRpcEvent,
-  packRpcMessages,
-  strToUint8Array,
-  uint8ArrayToBinaryStr,
-  uint8ArrayToStr,
-  unixTimestampSeconds
-};