Feat: Reveal Substring Template

package.json

@@ -1,5 +1,5 @@
 {
-  "version": "6.1.3",
+  "version": "6.1.5",
   "license": "MIT",
   "private": true,
   "scripts": {

packages/circuits/README.md

@@ -29,6 +29,9 @@ include "@zk-email/circuits/email-verifier.circom";
   - `n`: Number of bits per chunk the RSA key is split into. Recommended to be 121.
   - `k`: Number of chunks the RSA key is split into. Recommended to be 17.
   - `ignoreBodyHashCheck`: Set 1 to skip body hash check in case data to prove/extract is only in the headers.
+  - `enableHeaderMasking`: Set 1 to turn on header masking.
+  - `enableBodyMasking`: Set 1 to turn on body masking.
+  - `removeSoftLineBreaks`: Set 1 to remove soft line breaks (`=\r\n`) from the email body.
 
   `Note`: We use these values for n and k because their product (n * k) needs to be more than 2048 (RSA constraint) and n has to be less than half of 255 to fit in a circom signal.
 
@@ -41,10 +44,14 @@ include "@zk-email/circuits/email-verifier.circom";
   - `emailBodyLength`: Length of the email body including the SHA-256 padding.
   - `bodyHashIndex`: Index of the body hash `bh` in the `emailHeader`.
   - `precomputedSHA[32]`: Precomputed SHA-256 hash of the email body till the bodyHashIndex.
+  - `headerMask[maxHeadersLength]`: Mask to be applied on the `emailHeader`.
+  - `bodyMask[maxBodyLength]`: Mask to be applied on the `emailBody`.
+  - `decodedEmailBody[maxBodyLength]`: Decoded email body after removing soft line breaks.
 
   **Output Signal** 
   - `pubkeyHash`: Poseidon hash of the pubkey - Poseidon(n/2)(n/2 chunks of pubkey with k*2 bits per chunk).
-
+  - `maskedHeader[maxHeadersLength]`: Masked email header.
+  - `maskedBody[maxBodyLength]`: Masked email body.
 <br/>
 
 ## **Libraries**
@@ -257,6 +264,33 @@ DigitBytesToInt: Converts a byte array representing digits to an integer.
   - `out`: The output integer after conversion.
 </details>
 
+<details>
+<summary>
+AssertBit: Asserts that a given input is binary.
+</summary>
+
+- **[Source](utils/bytes.circom#L1-L7)**
+- **Inputs**:
+  - `in`: An input signal, expected to be 0 or 1.
+- **Outputs**:
+  - None. This template will throw an assertion error if the input is not binary.
+
+</details>
+
+<details>
+<summary>
+ByteMask: Masks an input array using a binary mask array.
+</summary>
+
+- **[Source](utils/bytes.circom#L9-L25)**
+- **Parameters**:
+  - `maxLength`: The maximum length of the input and mask arrays.
+- **Inputs**:
+  - `in`: An array of signals representing the body to be masked.
+  - `mask`: An array of signals representing the binary mask.
+- **Outputs**:
+  - `out`: An array of signals representing the masked input.
+</details>
 
 ### `utils/constants.circom`
 
@@ -359,5 +393,20 @@ EmailNullifier: Calculates the email nullifier using Poseidon hash.
   - `out`: The email nullifier.
 </details>
 
+### `helpers/remove-soft-line-breaks.circom`
+
+<details>
+<summary>
+RemoveSoftLineBreaks: Verifies the removal of soft line breaks from an encoded input string.
+</summary>
 
+- **[Source](helpers/remove-soft-line-breaks.circom)**
+- **Parameters**:
+  - `maxLength`: The maximum length of the input strings.
+- **Inputs**:
+  - `encoded[maxLength]`: An array of ASCII values representing the input string with potential soft line breaks.
+  - `decoded[maxLength]`: An array of ASCII values representing the expected output after removing soft line breaks.
+- **Outputs**:
+  - `isValid`: A signal that is 1 if the decoded input correctly represents the encoded input with soft line breaks removed, 0 otherwise.
 
+</details>

packages/circuits/email-verifier.circom

@@ -9,6 +9,7 @@ include "./lib/sha.circom";
 include "./utils/array.circom";
 include "./utils/regex.circom";
 include "./utils/hash.circom";
+include "./utils/bytes.circom";
 include "./helpers/remove-soft-line-breaks.circom";
 
 
@@ -21,6 +22,8 @@ include "./helpers/remove-soft-line-breaks.circom";
 /// @param n Number of bits per chunk the RSA key is split into. Recommended to be 121.
 /// @param k Number of chunks the RSA key is split into. Recommended to be 17.
 /// @param ignoreBodyHashCheck Set 1 to skip body hash check in case data to prove/extract is only in the headers.
+/// @param enableHeaderMasking Set 1 to turn on header masking.
+/// @param enableBodyMasking Set 1 to turn on body masking.
 /// @param removeSoftLineBreaks Set 1 to remove soft line breaks from the email body.
 /// @input emailHeader[maxHeadersLength] Email headers that are signed (ones in `DKIM-Signature` header) as ASCII int[], padded as per SHA-256 block size.
 /// @input emailHeaderLength Length of the email header including the SHA-256 padding.
@@ -31,9 +34,12 @@ include "./helpers/remove-soft-line-breaks.circom";
 /// @input bodyHashIndex Index of the body hash `bh` in the emailHeader.
 /// @input precomputedSHA[32] Precomputed SHA-256 hash of the email body till the bodyHashIndex.
 /// @input decodedEmailBodyIn[maxBodyLength] Decoded email body without soft line breaks.
+/// @input mask[maxBodyLength] Mask for the email body.
 /// @output pubkeyHash Poseidon hash of the pubkey - Poseidon(n/2)(n/2 chunks of pubkey with k*2 bits per chunk).
 /// @output decodedEmailBodyOut[maxBodyLength] Decoded email body with soft line breaks removed.
-template EmailVerifier(maxHeadersLength, maxBodyLength, n, k, ignoreBodyHashCheck, removeSoftLineBreaks) {
+/// @output maskedHeader[maxHeadersLength] Masked email header.
+/// @output maskedBody[maxBodyLength] Masked email body.
+template EmailVerifier(maxHeadersLength, maxBodyLength, n, k, ignoreBodyHashCheck, enableHeaderMasking, enableBodyMasking, removeSoftLineBreaks) {
     assert(maxHeadersLength % 64 == 0);
     assert(maxBodyLength % 64 == 0);
     assert(n * k > 2048); // to support 2048 bit RSA
@@ -85,6 +91,15 @@ template EmailVerifier(maxHeadersLength, maxBodyLength, n, k, ignoreBodyHashChec
     rsaVerifier.modulus <== pubkey;
     rsaVerifier.signature <== signature;
 
+    if (enableHeaderMasking == 1) {
+        signal input headerMask[maxHeadersLength];
+        signal output maskedHeader[maxHeadersLength];
+        component byteMask = ByteMask(maxHeadersLength);
+
+        byteMask.in <== emailHeader;
+        byteMask.mask <== headerMask;
+        maskedHeader <== byteMask.out;
+    }
 
     // Calculate the SHA256 hash of the body and verify it matches the hash in the header
     if (ignoreBodyHashCheck != 1) {
@@ -129,19 +144,25 @@ template EmailVerifier(maxHeadersLength, maxBodyLength, n, k, ignoreBodyHashChec
 
         if (removeSoftLineBreaks == 1) {
             signal input decodedEmailBodyIn[maxBodyLength];
-            signal output decodedEmailBodyOut[maxBodyLength];
             component qpEncodingChecker = RemoveSoftLineBreaks(maxBodyLength);
 
             qpEncodingChecker.encoded <== emailBody;
             qpEncodingChecker.decoded <== decodedEmailBodyIn;
 
             qpEncodingChecker.isValid === 1;
+        }
 
-            decodedEmailBodyOut <== qpEncodingChecker.decoded;
+        if (enableBodyMasking == 1) {
+            signal input bodyMask[maxBodyLength];
+            signal output maskedBody[maxBodyLength];
+            component byteMask = ByteMask(maxBodyLength);
+
+            byteMask.in <== emailBody;
+            byteMask.mask <== bodyMask;
+            maskedBody <== byteMask.out;
         }
     }
 
-
     // Calculate the Poseidon hash of DKIM public key as output
     // This can be used to verify (by verifier/contract) the pubkey used in the proof without needing the full key
     // Since PoseidonLarge concatenates nearby values its important to use same n/k (recommended 121*17) to produce uniform hashes

packages/circuits/helpers/remove-soft-line-breaks.circom

@@ -89,7 +89,12 @@ template RemoveSoftLineBreaks(maxLength) {
     }
 
     // Calculate powers of r for encoded
-    rEnc[0] <== 1;
+    muxEnc[0] = Mux1();
+    muxEnc[0].c[0] <== r;
+    muxEnc[0].c[1] <== 1;
+    muxEnc[0].s <== shouldZero[0];
+    rEnc[0] <== muxEnc[0].out;
+
     for (var i = 1; i < maxLength; i++) {
         muxEnc[i] = Mux1();
         muxEnc[i].c[0] <== rEnc[i - 1] * r;
@@ -99,19 +104,19 @@ template RemoveSoftLineBreaks(maxLength) {
     }
 
     // Calculate powers of r for decoded
-    rDec[0] <== 1;
+    rDec[0] <== r;
     for (var i = 1; i < maxLength; i++) {
         rDec[i] <== rDec[i - 1] * r;
     }
 
     // Calculate rlc for processed
-    sumEnc[0] <== processed[0];
+    sumEnc[0] <== rEnc[0] * processed[0];
     for (var i = 1; i < maxLength; i++) {
         sumEnc[i] <== sumEnc[i - 1] + rEnc[i] * processed[i];
     }
 
     // Calculate rlc for decoded
-    sumDec[0] <== decoded[0];
+    sumDec[0] <== rDec[0] * decoded[0];
     for (var i = 1; i < maxLength; i++) {
         sumDec[i] <== sumDec[i - 1] + rDec[i] * decoded[i];
     }

packages/circuits/helpers/reveal-substring.circom

@@ -0,0 +1,50 @@
+pragma circom 2.1.6;
+
+include "circomlib/circuits/comparators.circom";
+include "../utils/array.circom";
+
+/// @title RevealSubstring
+/// @notice This circuit reveals a substring from an input array and verifies its uniqueness
+/// @dev Ensures the revealed substring occurs exactly once in the input
+/// @dev Note: This circuit assumes that the consuming circuit handles input validation
+///      (e.g., checking that substringStartIndex and substringLength are within valid ranges)
+/// @param maxLength The maximum length of the input array
+/// @param maxSubstringLength The maximum length of the substring to be revealed
+template RevealSubstring(maxLength, maxSubstringLength, shouldCheckUniqueness) {
+    assert(maxSubstringLength < maxLength);
+
+    signal input in[maxLength];
+    signal input substringStartIndex;
+    signal input substringLength;
+
+    signal output substring[maxSubstringLength];
+
+    // Substring start index should be less than maxLength
+    signal isSubstringStartIndexValid <== LessThan(log2Ceil(maxLength))([substringStartIndex, maxLength]);
+    isSubstringStartIndexValid === 1;
+
+    // Substring length should be less than maxSubstringLength + 1
+    signal isSubstringLengthValid <== LessThan(log2Ceil(maxSubstringLength + 1))([substringLength, maxSubstringLength + 1]);
+    isSubstringLengthValid === 1;
+
+    // substring index + substring length should be less than maxLength + 1
+    signal sum <== substringStartIndex + substringLength;
+    signal isSumValid <== LessThan(log2Ceil(maxLength + 1))([sum, maxLength + 1]);
+    isSumValid === 1;
+
+    // Extract the substring
+    component selectSubArray = SelectSubArray(maxLength, maxSubstringLength);
+    selectSubArray.in <== in;
+    selectSubArray.startIndex <== substringStartIndex;
+    selectSubArray.length <== substringLength;
+
+    if (shouldCheckUniqueness) {
+        // Check if the substring occurs exactly once in the input
+        component countSubstringOccurrences = CountSubstringOccurrences(maxLength, maxSubstringLength);
+        countSubstringOccurrences.in <== in;
+        countSubstringOccurrences.substring <== selectSubArray.out;
+        countSubstringOccurrences.count === 1;
+    }
+
+    substring <== selectSubArray.out;
+}

packages/circuits/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zk-email/circuits",
-  "version": "6.1.3",
+  "version": "6.1.5",
   "license": "MIT",
   "scripts": {
     "publish": "yarn npm publish --access=public",
-    "test": "NODE_OPTIONS=--max_old_space_size=8192 jest tests"
+    "test": "NODE_OPTIONS=--max_old_space_size=8192 jest --runInBand --detectOpenHandles --forceExit --verbose tests"
   },
   "dependencies": {
     "@zk-email/zk-regex-circom": "^2.1.0",

packages/circuits/tests/base64.test.ts

@@ -1,58 +1,57 @@
 import { wasm } from "circom_tester";
 import path from "path";
 
-
 describe("Base64 Lookup", () => {
-  jest.setTimeout(10 * 60 * 1000); // 10 minutes
-
-  let circuit: any;
-
-  beforeAll(async () => {
-    circuit = await wasm(
-      path.join(__dirname, "./test-circuits/base64-test.circom"),
-      {
-        recompile: true,
-        include: path.join(__dirname, "../../../node_modules"),
-        // output: path.join(__dirname, "./compiled-test-circuits"),
-      }
-    );
-  });
-
-  it("should decode valid base64 chars", async function () {
-    const inputs = [
-      [65, 0], // A
-      [90, 25], // Z
-      [97, 26], // a
-      [122, 51], // z
-      [48, 52], // 0
-      [57, 61], // 9
-      [43, 62], // +
-      [47, 63], // /
-      [61, 0], // =
-    ]
-
-    for (const [input, output] of inputs) {
-      const witness = await circuit.calculateWitness({
-        in: input
-      });
-      await circuit.checkConstraints(witness);
-      await circuit.assertOut(witness, { out: output })
-    }
-  });
-
-  it("should fail with invalid chars", async function () {
-    const inputs = [34, 64, 91, 44];
-
-    expect.assertions(inputs.length);
-    for (const input of inputs) {
-    try {
-      const witness = await circuit.calculateWitness({
-        in: input
-      });
-      await circuit.checkConstraints(witness);
-    } catch (error) {
-      expect((error as Error).message).toMatch("Assert Failed");
-    }
-    }
-  });
+    jest.setTimeout(30 * 60 * 1000); // 30 minutes
+
+    let circuit: any;
+
+    beforeAll(async () => {
+        circuit = await wasm(
+            path.join(__dirname, "./test-circuits/base64-test.circom"),
+            {
+                recompile: true,
+                include: path.join(__dirname, "../../../node_modules"),
+                // output: path.join(__dirname, "./compiled-test-circuits"),
+            }
+        );
+    });
+
+    it("should decode valid base64 chars", async function () {
+        const inputs = [
+            [65, 0], // A
+            [90, 25], // Z
+            [97, 26], // a
+            [122, 51], // z
+            [48, 52], // 0
+            [57, 61], // 9
+            [43, 62], // +
+            [47, 63], // /
+            [61, 0], // =
+        ];
+
+        for (const [input, output] of inputs) {
+            const witness = await circuit.calculateWitness({
+                in: input,
+            });
+            await circuit.checkConstraints(witness);
+            await circuit.assertOut(witness, { out: output });
+        }
+    });
+
+    it("should fail with invalid chars", async function () {
+        const inputs = [34, 64, 91, 44];
+
+        expect.assertions(inputs.length);
+        for (const input of inputs) {
+            try {
+                const witness = await circuit.calculateWitness({
+                    in: input,
+                });
+                await circuit.checkConstraints(witness);
+            } catch (error) {
+                expect((error as Error).message).toMatch("Assert Failed");
+            }
+        }
+    });
 });